@servicetitan/stylelint-config 40.1.0 → 40.2.0

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

@@ -0,0 +1,414 @@
+import postcss from 'postcss';
+import type { Token } from '../load-tokens';
+
+/*
+ * Stylelint is ESM-only, and Jest can only load ESM-only packages on Node 24.9+ with
+ * --experimental-vm-modules, so the rule runs directly against a postcss tree with stylelint's
+ * plugin utilities replaced.
+ */
+jest.mock('stylelint', () => ({
+    createPlugin: (ruleName: string, rule: unknown) => ({ ruleName, rule }),
+    utils: {
+        ruleMessages: (_ruleName: string, messages: unknown) => messages,
+        report: mockReport,
+    },
+}));
+jest.mock('../load-tokens', () => ({
+    ...jest.requireActual('../load-tokens'),
+    loadTokens: () => mockTokens,
+}));
+
+const mockReport = jest.fn();
+const mockTokens: Token[] = [];
+
+describe('[stylelint-config] @servicetitan/use-tokens rule', () => {
+    const value = '#0265dc';
+    const designSystemToken: Token = {
+        name: 'color-blue-500',
+        customProperty: '--color-blue-500',
+        source: '@servicetitan/tokens',
+        value,
+    };
+    const anvil2Token: Token = {
+        name: 'color-blue-600',
+        customProperty: '--a2-color-blue-600',
+        source: '@servicetitan/anvil2',
+        value,
+    };
+
+    let declaration: string;
+    let codeFilename: string | undefined;
+    let fix: boolean;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockTokens.splice(0);
+        declaration = `color: ${value};`;
+        codeFilename = 'styles.css';
+        fix = false;
+    });
+
+    const subject = () => {
+        let rule: any;
+        // Rule initializes state when it loads, so load it after tests have set up tokens.
+        jest.isolateModules(() => (rule = require('../use-tokens').rule));
+        const root = postcss.parse(`a { ${declaration} }`);
+        rule(true, {}, { fix })(root, { opts: { from: codeFilename } });
+        return {
+            messages: mockReport.mock.calls.map(([{ message }]) => message),
+            words: mockReport.mock.calls.map(([{ word }]) => word),
+            code: root.toString(),
+        };
+    };
+
+    function itReportsNothing() {
+        test('reports nothing', () => {
+            expect(subject().messages).toEqual([]);
+        });
+    }
+
+    function itNegatesCustomPropertyWithCalc(customProperty: string) {
+        test('negates its custom property with calc()', () => {
+            expect(subject().messages[0]).toContain(`"calc(-1 * var(${customProperty}))"`);
+        });
+    }
+
+    itReportsNothing();
+
+    describe('when the value matches a design-system token', () => {
+        beforeEach(() => mockTokens.push({ ...designSystemToken }));
+
+        test('reports its custom property', () => {
+            expect(subject().messages).toEqual([
+                `You should use "var(${designSystemToken.customProperty})" from \`${designSystemToken.source}\` instead of "${value}".`,
+            ]);
+        });
+
+        describe('with a Less file', () => {
+            beforeEach(() => (codeFilename = 'styles.less'));
+
+            test('reports its Less variable', () => {
+                expect(subject().messages[0]).toContain(`"@${designSystemToken.name}"`);
+            });
+        });
+
+        describe.each(['styles.scss', 'styles.sass'])('with %s', filename => {
+            beforeEach(() => (codeFilename = filename));
+
+            test('reports its Sass variable', () => {
+                expect(subject().messages[0]).toContain(`"$${designSystemToken.name}"`);
+            });
+        });
+
+        describe('without a file name', () => {
+            beforeEach(() => (codeFilename = undefined));
+
+            test('reports its custom property', () => {
+                expect(subject().messages[0]).toContain(
+                    `"var(${designSystemToken.customProperty})"`
+                );
+            });
+        });
+
+        describe('when fixing', () => {
+            beforeEach(() => (fix = true));
+
+            test('replaces the value', () => {
+                expect(subject().code).toBe(
+                    `a { color: var(${designSystemToken.customProperty}); }`
+                );
+            });
+        });
+
+        describe.each([
+            ['an uppercase hex color', '#0265DC'],
+            ['an rgb() color', 'rgb(2, 101, 220)'],
+            ['a space-separated rgb() color', 'rgb(2 101 220)'],
+            ['an rgb() color among other values', '1px solid rgb(2, 101, 220)'],
+            ['a hex color in a gradient', 'linear-gradient(90deg, #0265dc 0%, #fff 100%)'],
+            [
+                'an rgb() color in a gradient',
+                'linear-gradient(90deg, rgb(2, 101, 220) 0%, #fff 100%)',
+            ],
+        ])('with %s', (_description, color) => {
+            beforeEach(() => (declaration = `color: ${color};`));
+
+            test('reports its custom property', () => {
+                expect(subject().messages[0]).toContain(
+                    `"var(${designSystemToken.customProperty})"`
+                );
+            });
+        });
+
+        describe.each([
+            ['a translucent rgba() color', 'rgba(2, 101, 220, 0.5)'],
+            ['a translucent hex color', '#0265dc80'],
+        ])('with %s', (_description, color) => {
+            beforeEach(() => (declaration = `color: ${color};`));
+
+            itReportsNothing();
+        });
+
+        describe('with a color among other values', () => {
+            beforeEach(() => (declaration = `border: 1px solid ${value};`));
+
+            test('reports only the color', () => {
+                expect(subject().messages).toEqual([
+                    expect.stringContaining(`"var(${designSystemToken.customProperty})"`),
+                ]);
+            });
+
+            test('reports the color as written', () => {
+                expect(subject().words).toEqual([value]);
+            });
+
+            describe('when fixing', () => {
+                beforeEach(() => (fix = true));
+
+                function itReplacesOnlyTheColor() {
+                    test('replaces only the color', () => {
+                        expect(subject().code).toBe(
+                            `a { border: 1px solid var(${designSystemToken.customProperty}); }`
+                        );
+                    });
+                }
+
+                itReplacesOnlyTheColor();
+
+                describe('with an rgb() color', () => {
+                    beforeEach(() => (declaration = 'border: 1px solid rgb(2, 101, 220);'));
+
+                    itReplacesOnlyTheColor();
+                });
+            });
+        });
+
+        describe('with several matching values', () => {
+            const spacing1: Token = {
+                ...designSystemToken,
+                name: 'spacing-1',
+                customProperty: '--spacing-1',
+                value: '8px',
+            };
+            const spacing2: Token = {
+                ...designSystemToken,
+                name: 'spacing-2',
+                customProperty: '--spacing-2',
+                value: '16px',
+            };
+
+            beforeEach(() => {
+                mockTokens.push(spacing1, spacing2);
+                declaration = `margin: ${spacing1.value} ${spacing2.value};`;
+            });
+
+            test('reports each value', () => {
+                expect(subject().messages).toEqual([
+                    expect.stringContaining(`"var(${spacing1.customProperty})"`),
+                    expect.stringContaining(`"var(${spacing2.customProperty})"`),
+                ]);
+            });
+
+            describe('when fixing', () => {
+                beforeEach(() => (fix = true));
+
+                test('replaces each value', () => {
+                    expect(subject().code).toBe(
+                        `a { margin: var(${spacing1.customProperty}) var(${spacing2.customProperty}); }`
+                    );
+                });
+            });
+
+            describe('with a negative value', () => {
+                beforeEach(() => (declaration = `margin: -${spacing2.value};`));
+
+                itNegatesCustomPropertyWithCalc(spacing2.customProperty);
+
+                test('reports the value with its minus sign', () => {
+                    expect(subject().words).toEqual([`-${spacing2.value}`]);
+                });
+
+                describe('with a Sass file', () => {
+                    beforeEach(() => (codeFilename = 'styles.scss'));
+
+                    test('negates its Sass variable', () => {
+                        expect(subject().messages[0]).toContain(`"-$${spacing2.name}"`);
+                    });
+                });
+
+                describe('with a Less file', () => {
+                    beforeEach(() => (codeFilename = 'styles.less'));
+
+                    test('negates its Less variable', () => {
+                        expect(subject().messages[0]).toContain(`"-@${spacing2.name}"`);
+                    });
+                });
+
+                describe('when fixing', () => {
+                    beforeEach(() => (fix = true));
+
+                    test('replaces the value', () => {
+                        expect(subject().code).toBe(
+                            `a { margin: calc(-1 * var(${spacing2.customProperty})); }`
+                        );
+                    });
+                });
+            });
+        });
+
+        describe.each([
+            ['typescale-2', 'font-size', '14px', '14px'],
+            ['border-radius-1', 'border-radius', '3px', '3px'],
+            ['border-radius-0', 'border-radius', '0px', '0'],
+            ['border-radius-1', 'border-top-left-radius', '3px', '3px'],
+            ['spacing-1', 'margin', '8px', '8px'],
+            ['spacing-0', 'margin', '0px', '0'],
+            ['font-weight-semibold', 'font-weight', '600', '600'],
+            ['opacity-disabled', 'opacity', '0.6', '.6'],
+            ['opacity-disabled', 'opacity', '.6', '.6'],
+            ['z-index-drawer', 'z-index', '1100', '1100'],
+            ['base-line-height', 'line-height', '1.5', '1.5'],
+            [
+                'base-font-family',
+                'font-family',
+                "'Nunito Sans', sans-serif",
+                "'Nunito Sans', sans-serif",
+            ],
+        ])('when %s replaces %s: %s', (name, property, literal, tokenValue) => {
+            beforeEach(() => {
+                Object.assign(mockTokens[0], {
+                    name,
+                    customProperty: `--${name}`,
+                    value: tokenValue,
+                });
+                declaration = `${property}: ${literal};`;
+            });
+
+            test(`reports var(--${name})`, () => {
+                expect(subject().messages[0]).toContain(`"var(--${name})"`);
+            });
+        });
+    });
+
+    describe('when the value matches an anvil2 token', () => {
+        beforeEach(() => mockTokens.push({ ...anvil2Token }));
+
+        test('reports its custom property', () => {
+            expect(subject().messages).toEqual([
+                `You should use "var(${anvil2Token.customProperty})" from \`${anvil2Token.source}\` instead of "${value}".`,
+            ]);
+        });
+
+        describe('with a Less file', () => {
+            beforeEach(() => (codeFilename = 'styles.less'));
+
+            test('reports its custom property', () => {
+                expect(subject().messages[0]).toContain(`"var(${anvil2Token.customProperty})"`);
+            });
+        });
+
+        describe('with a Sass file', () => {
+            beforeEach(() => (codeFilename = 'styles.scss'));
+
+            test('reports its Sass variable', () => {
+                expect(subject().messages[0]).toContain(`"$${anvil2Token.name}"`);
+            });
+        });
+
+        describe('with an unsupported color format', () => {
+            beforeEach(() => (mockTokens[0].value = 'oklch(70% 0.1 200)'));
+
+            itReportsNothing();
+        });
+
+        describe('with a negative spacing value', () => {
+            const spacing: Pick<Token, 'name' | 'customProperty' | 'value'> = {
+                name: 'size-1',
+                customProperty: '--a2-size-1',
+                value: '0.25rem',
+            };
+
+            beforeEach(() => {
+                Object.assign(mockTokens[0], spacing);
+                declaration = `margin: -${spacing.value};`;
+            });
+
+            itNegatesCustomPropertyWithCalc(spacing.customProperty);
+
+            describe('with a Sass file', () => {
+                beforeEach(() => (codeFilename = 'styles.scss'));
+
+                test('negates its Sass variable with calc()', () => {
+                    expect(subject().messages[0]).toContain(`"calc(-1 * $${spacing.name})"`);
+                });
+            });
+
+            describe('with a Less file', () => {
+                beforeEach(() => (codeFilename = 'styles.less'));
+
+                itNegatesCustomPropertyWithCalc(spacing.customProperty);
+            });
+        });
+
+        describe.each([
+            ['font-size-300', 'font-size', '0.875rem'],
+            ['radius-1', 'border-radius', '0.1875rem'],
+            ['size-1', 'padding', '0.25rem'],
+            ['font-weight-bold', 'font-weight', '700'],
+            ['font-line-height-base', 'line-height', '1.5'],
+            ['font-family-base', 'font-family', "'Nunito Sans', sans-serif"],
+        ])('when %s replaces %s: %s', (name, property, value) => {
+            beforeEach(() => {
+                Object.assign(mockTokens[0], { name, customProperty: `--a2-${name}`, value });
+                declaration = `${property}: ${value};`;
+            });
+
+            test(`reports var(--a2-${name})`, () => {
+                expect(subject().messages[0]).toContain(`"var(--a2-${name})"`);
+            });
+        });
+    });
+
+    describe('when the value matches tokens from both packages', () => {
+        beforeEach(() => mockTokens.push({ ...designSystemToken }, { ...anvil2Token }));
+
+        test('reports every match', () => {
+            expect(subject().messages).toEqual([
+                `You should use "var(${designSystemToken.customProperty})" from \`${designSystemToken.source}\`` +
+                    ` or "var(${anvil2Token.customProperty})" from \`${anvil2Token.source}\` instead of "${value}".`,
+            ]);
+        });
+
+        describe('when fixing', () => {
+            beforeEach(() => (fix = true));
+
+            test('leaves the value', () => {
+                expect(subject().code).toBe(`a { ${declaration} }`);
+            });
+        });
+
+        describe('when the tokens share a name', () => {
+            const name = 'color-shared';
+
+            beforeEach(() => mockTokens.forEach(token => (token.name = name)));
+
+            describe('with a Sass file', () => {
+                beforeEach(() => (codeFilename = 'styles.scss'));
+
+                test('reports the shared variable once', () => {
+                    expect(subject().messages).toEqual([
+                        `You should use "$${name}" from \`${mockTokens[0].source}\` instead of "${value}".`,
+                    ]);
+                });
+
+                describe('when fixing', () => {
+                    beforeEach(() => (fix = true));
+
+                    test('replaces the value', () => {
+                        expect(subject().code).toBe(`a { color: $${name}; }`);
+                    });
+                });
+            });
+        });
+    });
+});

package/src/use-tokens/index.ts

@@ -1,163 +1,3 @@
-import Color from 'color';
-import { Rule, createPlugin, utils } from 'stylelint';
-import {
-    borderRadiuses,
-    colors,
-    fontFamilies,
-    fontWeights,
-    lineHeights,
-    opacities,
-    spacings,
-    typescales,
-    zIndexes,
-} from './values';
+import plugin from './use-tokens';
 
-const ruleName = '@servicetitan/use-tokens';
-const messages = utils.ruleMessages(ruleName, {
-    variableExpected: (expected: string, found: string) =>
-        `You should use "${expected}" variable from the \`@servicetitan/tokens\` instead of "${found}".`,
-});
-
-const plugin: Rule = (_0, _1, context) => {
-    return (root, result) => {
-        const extension = result.opts?.from?.split('.').pop()?.toLowerCase();
-
-        function convertToVariable(key: string) {
-            switch (extension) {
-                case 'less':
-                    return `@${key}`;
-
-                case 'sass':
-                case 'scss':
-                    return `$${key}`;
-
-                default:
-                    return `var(--${key})`;
-            }
-        }
-
-        root.walkDecls(decl => {
-            function lint(
-                collection: Record<string, string>,
-                {
-                    condition,
-                    transformer,
-                    solid,
-                }: {
-                    condition?: (property: string) => boolean;
-                    transformer?: (value: string) => string;
-                    solid?: boolean;
-                } = {}
-            ) {
-                if (condition && !condition(decl.prop)) {
-                    return true;
-                }
-
-                const values = !solid ? decl.value.split(' ') : [decl.value];
-
-                let reported = false;
-                for (const rawValue of values) {
-                    const value = transformer?.(rawValue) ?? rawValue;
-                    if (collection[value]) {
-                        const variable =
-                            (rawValue.startsWith('-') ? '-' : '') +
-                            convertToVariable(collection[value]);
-
-                        if (context.fix) {
-                            values[values.indexOf(rawValue)] = variable;
-                        } else {
-                            utils.report({
-                                node: decl,
-                                message: messages.variableExpected(variable, rawValue),
-                                word: value,
-                                ruleName,
-                                result,
-                            });
-                        }
-                        reported = true;
-                    }
-                }
-
-                if (context.fix) {
-                    decl.value = values.join(' ');
-                }
-
-                return !reported;
-            }
-
-            const linters = {
-                colors: () =>
-                    lint(colors, {
-                        transformer: value => {
-                            try {
-                                return new Color(value).hex();
-                            } catch {
-                                return '';
-                            }
-                        },
-                    }),
-
-                typescales: () =>
-                    lint(typescales, {
-                        condition: property => property === 'font-size',
-                        solid: true,
-                    }),
-
-                borderRadiuses: () =>
-                    lint(borderRadiuses, {
-                        condition: property =>
-                            property.startsWith('border-') && property.endsWith('-radius'),
-                        transformer: value => (value === '0px' ? '0' : value),
-                    }),
-
-                lintSpacings: () =>
-                    lint(spacings, {
-                        // other spacings like "top"?
-                        condition: property =>
-                            property.startsWith('margin') || property.startsWith('padding'),
-                        transformer: value =>
-                            value === '0px' ? '0' : value.startsWith('-') ? value.slice(1) : value,
-                    }),
-
-                fontWeights: () =>
-                    lint(fontWeights, {
-                        condition: property => property === 'font-weight',
-                        solid: true,
-                    }),
-
-                opacities: () =>
-                    lint(opacities, {
-                        condition: property => property === 'opacity',
-                        transformer: value => (value.startsWith('0.') ? value.slice(1) : value),
-                        solid: true,
-                    }),
-
-                zIndexes: () =>
-                    lint(zIndexes, { condition: property => property === 'z-index', solid: true }),
-
-                lineHeights: () =>
-                    lint(lineHeights, {
-                        condition: property => property === 'line-height',
-                        solid: true,
-                    }),
-
-                fontFamilies: () =>
-                    lint(fontFamilies, {
-                        condition: property => property === 'font-family',
-                        solid: true,
-                    }),
-            };
-
-            for (const handler of Object.values(linters)) {
-                if (!handler()) {
-                    return;
-                }
-            }
-        });
-    };
-};
-
-plugin.ruleName = ruleName;
-plugin.messages = messages;
-
-export = Object.assign(createPlugin(ruleName, plugin), { ruleName, messages });
+export = plugin;

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

@@ -0,0 +1,103 @@
+import fs from 'fs';
+
+export const DESIGN_SYSTEM_SOURCE = '@servicetitan/tokens';
+export const ANVIL2_SOURCE = '@servicetitan/anvil2';
+export type TokenSource = typeof DESIGN_SYSTEM_SOURCE | typeof ANVIL2_SOURCE;
+
+export interface Token {
+    /* Kebab-case name of the token's Less and Sass variables. */
+    name: string;
+    /* CSS custom property that holds the token's value at runtime. */
+    customProperty: string;
+    source: TokenSource;
+    value: string;
+}
+
+/*
+ * Loads tokens from whichever token packages are installed. Both are optional peers, so a
+ * missing package contributes no tokens.
+ */
+export function loadTokens(): Token[] {
+    return [...loadDesignSystemTokens(), ...loadAnvil2Tokens()];
+}
+
+function loadDesignSystemTokens(): Token[] {
+    const tokens = optionalRequire<{ tokens: Record<string, string> }>(
+        '@servicetitan/tokens/core'
+    )?.tokens;
+    if (!tokens) {
+        return [];
+    }
+
+    /*
+     * An alias is a second name for a value a canonical token already holds, for example
+     * "@default-border-radius: 3px; // (alias)" duplicates "@border-radius-1: 3px". Excluding
+     * aliases limits suggestions to the canonical name.
+     */
+    const aliases = fs
+        .readFileSync(require.resolve('@servicetitan/tokens/core/tokens.less'), 'utf8')
+        .split('\n')
+        .filter(row => row.startsWith('@') && row.endsWith('(alias)'))
+        .map(row => row.split(':')[0].slice(1));
+
+    return Object.entries(tokens)
+        .map(([key, value]) => ({ name: toKebabCase(key), value }))
+        .filter(({ name }) => !aliases.includes(name))
+        .map(({ name, value }) => ({
+            name,
+            customProperty: `--${name}`,
+            source: DESIGN_SYSTEM_SOURCE,
+            value,
+        }));
+}
+
+function loadAnvil2Tokens(): Token[] {
+    const primitives = optionalRequire<{
+        core: { primitive: Record<string, { value: string }> };
+    }>('@servicetitan/anvil2/token')?.core.primitive;
+    if (!primitives) {
+        return [];
+    }
+
+    const version = optionalRequire<{ version: string }>(
+        '@servicetitan/anvil2/package.json'
+    )?.version;
+    /*
+     * Anvil2 v3 prefixes its CSS custom properties with "a2-". All versions <3
+     * export package.json, so a version that doesn't is v3 or later.
+     */
+    const prefix = version === undefined || parseInt(version, 10) >= 3 ? 'a2-' : '';
+
+    return Object.entries(primitives).map(([key, { value }]) => {
+        const name = toKebabCase(key);
+        return {
+            name,
+            customProperty: `--${prefix}${name}`,
+            source: ANVIL2_SOURCE,
+            value,
+        };
+    });
+}
+
+/*
+ * Returns undefined when the package isn't installed, or is a version that doesn't export the
+ * requested path.
+ */
+function optionalRequire<T>(id: string): T | undefined {
+    try {
+        return require(id);
+    } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === 'MODULE_NOT_FOUND' || code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+
+function toKebabCase(str: string) {
+    const camelCase = str.charAt(0).toLowerCase() + str.slice(1);
+    return camelCase.replace(/([A-Z]|[a-z]\d)/g, ([letter, digit]) =>
+        digit === undefined ? `-${letter.toLowerCase()}` : `${letter}-${digit}`
+    );
+}