The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
#!/usr/bin/env tsx
/* eslint-disable no-console */
import { readFileSync } from "fs";
import { glob } from "glob";
import { ALL_COLOR_NAMES } from "../../frontend/src/metabase/ui/colors";
/**
* This script finds css variables that are used but *never* defined in our codebase.
* Its goal isn't to find usages of variables in contexts where that variable is not defined,
* as that would be a lot harder.
* Its goal is to prevent typos and wrong usages created by conflicts and backports.
* The most common thing this should catch and prevent is backporting a fix or feature that uses a css variable
* that doesn't exist in the release branch.
*/
const shouldWhiteList = (variable: string) => {
// Use this for whitelisting some variables if we know they're defined by a 3rd party, such as mantine
// Note: Be sure not to backport changes to this function that would whitelist variables not on the release branch
if (knownIssues.includes(variable)) {
return true;
}
return false;
};
// These are variables that were found by the script but were temporarily allowed to get this script + mantine v7 merged
const knownIssues = [
"--button-bg", // Mantine var defined for buttons and used in Button.module.css
// `accent-gray-light` is one of our theme colors (registered via getMantineThemeColors).
// Mantine derives variant vars like `--mantine-color-<color>-filled` from each registered
// color at runtime, so they aren't in the static @mantine/core/styles.css this script
// reads — hence this allow-list entry.
"--mantine-color-accent-gray-light-filled",
// Custom spacing/radius scale keys. Mantine derives
// `--mantine-spacing-*` / `--mantine-radius-*` variables at runtime from the
// theme object in frontend/src/metabase/ui/theme.ts, so they are not in the
// static @mantine/core/styles.css this script reads.
"--mantine-spacing-xxxs",
"--mantine-spacing-xxs",
"--mantine-spacing-xxl",
"--mantine-radius-xxs",
"--mantine-shadow-xs_outline",
"--mantine-shadow-sm_outline",
"--mantine-shadow-lg_outline",
"--mantine-shadow-xs_on_dark",
];
interface UsageMap {
// variable : files
[variable: string]: string[];
}
const findFiles = (): string[] => {
return glob
.sync(
"{frontend,enterprise/frontend,.storybook}/**/*.{css,module.css,js,jsx,ts,tsx}",
)
.filter((f) => !/\.(unit\.spec|spec|test)\.(js|jsx|ts|tsx)$/.test(f));
};
const extractVariableDefinitions = (filePath: string): Set<string> => {
const fileContent = readFileSync(filePath, "utf8");
return extractVariableDefinitionsFromFileContent(fileContent);
};
export const extractVariableDefinitionsFromFileContent = (
fileContent: string,
): Set<string> => {
const patterns = [
/--[a-zA-Z0-9_-]+:/g, // css files: --my-css-variable: blue
/['"`]--[a-zA-Z0-9_-]+['"`]\s*:/g, // css-in-js: "--my-css-variable-in-emotion": blue
];
const matches = patterns.flatMap((pattern) => {
const found = fileContent.match(pattern) || [];
return found.map((match) => {
const cleaned = match.replace(/['"`{}:,\s]/g, "");
return cleaned;
});
});
return new Set(matches);
};
const extractVariableUsages = (filePath: string): Set<string> => {
const content = readFileSync(filePath, "utf8");
return extractVariableUsagesFromFileContent(content);
};
export const extractVariableUsagesFromFileContent = (
content: string,
): Set<string> => {
const pattern = /var\(\s*(--[a-zA-Z0-9_-]+)\s*([,)])/g;
const usages = Array.from(content.matchAll(pattern)).flatMap((match) => {
const [, variable, terminator] = match;
const hasFallback = terminator === ",";
// A bare `var(--x)` must resolve to a defined variable. A `var(--x, fallback)`
// is safe by construction — unless it's one of our `--mb-*` design-system
// primitives, which are expected to always be defined
const shouldValidate = !hasFallback || variable.startsWith("--mb-");
return shouldValidate ? [variable] : [];
});
return new Set(usages);
};
const main = () => {
const files = findFiles();
const allDefinitions = new Set<string>();
const allUsages = new Set<string>();
const usageLocations: UsageMap = {};
const mantineDefinitions = extractVariableDefinitions(
"node_modules/@mantine/core/styles.css",
);
for (const definition of mantineDefinitions) {
allDefinitions.add(definition);
}
ALL_COLOR_NAMES.forEach((key) => {
allDefinitions.add(`--mb-color-${key}`);
});
// Find all variable definitions
files.forEach((file) => {
const definitions = extractVariableDefinitions(file);
definitions.forEach((def) => allDefinitions.add(def));
});
// Find all variable usages
files.forEach((file) => {
const usages = extractVariableUsages(file);
usages.forEach((usage) => {
allUsages.add(usage);
if (!usageLocations[usage]) {
usageLocations[usage] = [];
}
usageLocations[usage].push(file);
});
});
// Filter out defined or whitelisted variables
const undefinedVars = Array.from(allUsages)
.filter((usage) => !allDefinitions.has(usage) && !shouldWhiteList(usage))
.sort();
if (undefinedVars.length > 0) {
console.log("Found undefined CSS variables:\n");
undefinedVars.forEach((variable) => {
console.log(`${variable} used in:`);
usageLocations[variable].forEach((location) => {
console.log(` - ${location}`);
});
console.log("");
});
const filesWithUndefinedVars = new Set(
undefinedVars.map((variable) => usageLocations[variable]).flat(),
);
console.log(
`Found ${undefinedVars.length} CSS variables that were used but never defined in ${filesWithUndefinedVars.size} files\n`,
);
console.log(
"See bin/find-never-defined-css-variables/find-never-defined-css-variables.ts for more details\n",
);
process.exit(1);
} else {
console.log("No undefined CSS variables found");
process.exit(0);
}
};
if (require.main === module) {
main();
}