@atlaskit/eslint-plugin-design-system
Version:
The essential plugin for use with the Atlassian Design System.
610 lines (581 loc) • 25.7 kB
JavaScript
import { isNodeOfType } from 'eslint-codemod-utils';
import { createLintRule } from '../utils/create-lint-rule';
import { isImportFromPackage } from '../utils/is-import-from-package';
const LOZENGE_IMPORT_SOURCES = new Set(['@atlaskit/lozenge', '@atlaskit/lozenge/lozenge']);
const BADGE_IMPORT_SOURCES = new Set(['@atlaskit/badge', '@atlaskit/badge/badge']);
const SIMPLE_TAG_IMPORT_SOURCES = new Set(['@atlaskit/tag/simple-tag']);
const REMOVABLE_TAG_IMPORT_SOURCES = new Set(['@atlaskit/tag', '@atlaskit/tag/removable-tag']);
const AVATAR_IMPORT_SOURCES = new Set(['@atlaskit/avatar', '@atlaskit/avatar/avatar', '@atlaskit/avatar/Avatar']);
const rule = createLintRule({
meta: {
name: 'lozenge-badge-tag-labelling-system-migration',
fixable: 'code',
type: 'suggestion',
docs: {
description: 'Migrates legacy Lozenge and Badge appearance values and guides SimpleTag/RemovableTag migrations to the supported Tag APIs.',
recommended: false,
severity: 'warn'
},
messages: {
updateAppearance: 'Replace Lozenge appearance="{{oldValue}}" with appearance="{{newValue}}"; apply the autofix.',
migrateTag: '{{remedy}} {{reason}} See the lozenge-badge-tag-labelling-system-migration README in @atlaskit/eslint-plugin-design-system for examples.',
updateBadgeAppearance: 'Update Badge appearance value "{{oldValue}}" to new semantic value "{{newValue}}".',
dynamicBadgeAppearance: 'Dynamic appearance prop values require manual review to ensure they use the new semantic values: neutral, information, inverse, danger, success.'
}
},
create(context) {
/**
* Contains a map of imported Lozenge components.
*/
const lozengeImports = {}; // local name -> import source
/**
* Contains a map of imported Badge components.
*/
const badgeImports = {}; // local name -> import source
/**
* Contains a map of imported Tag components (SimpleTag, RemovableTag, or default Tag imports).
* Maps local name to { type: 'SimpleTag' | 'RemovableTag' | 'Tag', source: string, node: ImportNode }
*/
const tagImports = {};
/**
* Contains a map of imported Avatar components from @atlaskit/avatar.
* Maps local name to import source
*/
const avatarImports = {};
/**
* Contains a map of imported Tag and AvatarTag components from @atlaskit/tag.
* These are the new components that should not be migrated.
* Maps local name to import source
*/
const newTagImports = {};
/**
* Check if a JSX attribute value is dynamic (not a static literal value)
* Can be used for any prop type (boolean, string, etc.)
*/
function isDynamicExpression(node) {
if (!node) {
return false;
}
// If it's a plain literal (e.g., appearance="value"), it's not dynamic
if (node.type === 'Literal') {
return false;
}
// If it's an expression container with a non-literal expression, it's dynamic
if (node.type === 'JSXExpressionContainer') {
const expr = node.expression;
return expr && expr.type !== 'Literal';
}
return false;
}
/**
* Get all attributes as an object for easier manipulation
*/
function getAttributesMap(attributes) {
const map = {};
attributes.forEach(attr => {
if (attr.type === 'JSXAttribute' && attr.name.type === 'JSXIdentifier') {
map[attr.name.name] = attr;
}
});
return map;
}
/**
* Map old Lozenge appearance values to new semantic appearance values.
* The new Lozenge no longer uses legacy values — it uses semantic color names
* that align with the new labelling system.
*/
function mapToNewAppearanceValue(oldValue) {
const mapping = {
default: 'neutral',
inprogress: 'information',
moved: 'warning',
removed: 'danger',
new: 'discovery',
success: 'success'
};
return mapping[oldValue] || oldValue;
}
/**
* Map Badge old appearance values to new semantic appearance values
*/
function mapBadgeToNewAppearanceValue(oldValue) {
const mapping = {
added: 'success',
removed: 'danger',
default: 'neutral',
primary: 'information',
primaryInverted: 'inverse',
important: 'danger'
};
return mapping[oldValue] || oldValue;
}
/**
* Map Tag color light variants to semantic color values
*/
function mapTagColorValue(oldValue) {
const mapping = {
limeLight: 'lime',
orangeLight: 'orange',
magentaLight: 'magenta',
greenLight: 'green',
blueLight: 'blue',
redLight: 'red',
purpleLight: 'purple',
greyLight: 'gray',
tealLight: 'teal',
yellowLight: 'yellow',
grey: 'gray'
};
return mapping[oldValue] || oldValue;
}
/**
* Check if elemBefore prop contains only an Avatar component from @atlaskit/avatar
* Returns the Avatar component name if it's from the avatar package, null otherwise
*/
function getAvatarComponentName(elemBeforeProp) {
const getJsxIdentifierName = node => {
return (node === null || node === void 0 ? void 0 : node.type) === 'JSXIdentifier' ? node.name : null;
};
if (!elemBeforeProp || !elemBeforeProp.value) {
return null;
}
const value = elemBeforeProp.value;
// Check for JSX element: <Avatar ... />
if (value.type === 'JSXElement') {
const avatarName = getJsxIdentifierName(value.openingElement.name);
if (!avatarName) {
return null;
}
if (avatarImports[avatarName]) {
return avatarName;
}
}
// Check for JSX expression container: {<Avatar ... />}
if (value.type === 'JSXExpressionContainer' && value.expression) {
// Direct JSX element: {<Avatar ... />}
if (value.expression.type === 'JSXElement' && getJsxIdentifierName(value.expression.openingElement.name)) {
const avatarName = getJsxIdentifierName(value.expression.openingElement.name);
if (!avatarName) {
return null;
}
if (avatarImports[avatarName]) {
return avatarName;
}
}
// Arrow function: {() => <Avatar ... />}
if (value.expression.type === 'ArrowFunctionExpression') {
const body = value.expression.body;
if (body.type === 'JSXElement') {
const avatarName = getJsxIdentifierName(body.openingElement.name);
if (!avatarName) {
return null;
}
if (avatarImports[avatarName]) {
return avatarName;
}
}
}
}
return null;
}
/**
* Check if color prop value needs mapping
*/
function colorNeedsMapping(colorProp) {
if (!(colorProp !== null && colorProp !== void 0 && colorProp.value)) {
return false;
}
const stringValue = extractStringValue(colorProp.value);
return stringValue !== null && typeof stringValue === 'string' && mapTagColorValue(stringValue) !== stringValue;
}
/**
* Extract the string value from a JSX attribute value
*/
function extractStringValue(attrValue) {
if (!attrValue) {
return null;
}
if (attrValue.type === 'Literal') {
return attrValue.value;
}
if (attrValue.type === 'JSXExpressionContainer' && attrValue.expression && attrValue.expression.type === 'Literal') {
return attrValue.expression.value;
}
return null;
}
/**
* Create a fixer function to replace an appearance prop value
* Handles both Literal and JSXExpressionContainer with Literal
*/
function createAppearanceFixer(attrValue, newValue) {
return fixer => {
if (!attrValue) {
return null;
}
if (attrValue.type === 'Literal') {
return fixer.replaceText(attrValue, `"${newValue}"`);
}
if (attrValue.type === 'JSXExpressionContainer' && 'expression' in attrValue && attrValue.expression && attrValue.expression.type === 'Literal') {
return fixer.replaceText(attrValue.expression, `"${newValue}"`);
}
return null;
};
}
// Only rewrite an isolated, statically understood plain Tag. Other uses retain
// diagnostics so the migration can account for their bindings and behavior.
function getPlainTagFix(node, info) {
var _context$sourceCode, _info$node;
// @ts-ignore - Jira's ESLint v10 types expose sourceCode, platform still checks with ESLint v9.
const sourceCode = (_context$sourceCode = context.sourceCode) !== null && _context$sourceCode !== void 0 ? _context$sourceCode : context.getSourceCode();
const declaration = (_info$node = info.node) === null || _info$node === void 0 ? void 0 : _info$node.parent;
if (!declaration || declaration.specifiers.length !== 1) {
return {
reason: 'Migrate the mixed import manually, preserving every remaining binding.'
};
}
if (sourceCode.getCommentsInside(node).length > 0) {
return {
reason: 'Preserve component comments while migrating manually.'
};
}
if (sourceCode.getCommentsInside(declaration).length > 0) {
return {
reason: 'Preserve the import comments while migrating manually.'
};
}
if (sourceCode.ast.body.some(statement => statement.type === 'ImportDeclaration' && statement.source.value === '@atlaskit/tag/tag-new')) {
return {
reason: 'Reuse the existing tag-new import after checking its local binding.'
};
}
const attrs = node.openingElement.attributes;
const supported = new Set(['text', 'color', 'elemBefore', 'testId', 'href', 'removeButtonLabel', 'isRemovable']);
const seen = new Set();
let text;
for (const attr of attrs) {
if (attr.type !== 'JSXAttribute' || attr.name.type !== 'JSXIdentifier' || !supported.has(attr.name.name) || seen.has(attr.name.name)) {
return {
reason: 'Review spread, duplicate, and unsupported props against TagNewProps before migrating.'
};
}
seen.add(attr.name.name);
const value = extractStringValue(attr.value);
if (attr.name.name === 'elemBefore') {
var _attr$value;
const elemBefore = ((_attr$value = attr.value) === null || _attr$value === void 0 ? void 0 : _attr$value.type) === 'JSXExpressionContainer' ? attr.value.expression : attr.value;
if ((elemBefore === null || elemBefore === void 0 ? void 0 : elemBefore.type) !== 'JSXElement' && (elemBefore === null || elemBefore === void 0 ? void 0 : elemBefore.type) !== 'JSXFragment' && !((elemBefore === null || elemBefore === void 0 ? void 0 : elemBefore.type) === 'Literal' && typeof elemBefore.value === 'string')) {
return {
reason: 'Pass through only a static ReactNode elemBefore; review callbacks and dynamic values manually.'
};
}
}
if (attr.name.name === 'text' && typeof value === 'string') {
text = value;
}
if (attr.name.name === 'isRemovable') {
var _attr$value2;
const expression = ((_attr$value2 = attr.value) === null || _attr$value2 === void 0 ? void 0 : _attr$value2.type) === 'JSXExpressionContainer' ? attr.value.expression : attr.value;
if (info.type === 'SimpleTag' || attr.value && !((expression === null || expression === void 0 ? void 0 : expression.type) === 'Literal' && typeof expression.value === 'boolean')) {
return {
reason: 'Set removability explicitly after reviewing the legacy component behavior.'
};
}
} else if (attr.name.name !== 'elemBefore' && typeof value !== 'string') {
return {
reason: 'Check dynamic prop values against TagNewProps before migrating.'
};
}
if (attr.name.name === 'color' && !new Set(['gray', 'blue', 'red', 'yellow', 'green', 'teal', 'purple', 'lime', 'orange', 'magenta']).has(mapTagColorValue(value))) {
return {
reason: 'Choose a supported NewTagColor before migrating.'
};
}
}
if (node.children.length > 0) {
if (seen.has('text')) {
return {
reason: 'Compare the text prop with its children before migrating.'
};
}
const [child] = node.children;
if (node.children.length !== 1 || child.type !== 'JSXText' || typeof child.value !== 'string' || child.value.length === 0 || child.value.trim() !== child.value) {
return {
reason: 'Review children manually; only one plain text child can be copied to the new Tag text prop safely.'
};
}
text = child.value;
} else if (!seen.has('text')) {
return {
reason: 'Supply the required text prop before migrating.'
};
}
const names = new Set();
let otherUse = false;
const visit = current => {
if (current.type === 'Identifier' || current.type === 'JSXIdentifier') {
var _node$closingElement;
names.add(current.name);
if (current.name === node.openingElement.name.name && !(current.range[0] >= declaration.range[0] && current.range[1] <= declaration.range[1]) && current !== node.openingElement.name && current !== ((_node$closingElement = node.closingElement) === null || _node$closingElement === void 0 ? void 0 : _node$closingElement.name)) {
otherUse = true;
}
}
for (const key of (_sourceCode$visitorKe = sourceCode.visitorKeys[current.type]) !== null && _sourceCode$visitorKe !== void 0 ? _sourceCode$visitorKe : []) {
var _sourceCode$visitorKe;
const child = current[key];
if (Array.isArray(child)) {
child.forEach(item => item && visit(item));
} else if (child) {
visit(child);
}
}
};
visit(sourceCode.ast);
if (otherUse) {
return {
reason: 'Migrate every use of this binding together; a single-site fix would break other references.'
};
}
names.delete(node.openingElement.name.name);
let name = 'Tag';
let suffix = 1;
while (names.has(name)) {
name = suffix === 1 ? 'MigratedTag' : `MigratedTag${suffix}`;
suffix++;
}
return {
reason: 'Apply the autofix for this isolated plain Tag.',
name,
text,
hasTextProp: seen.has('text')
};
}
return {
ImportDeclaration(node) {
const moduleSource = node.source.value;
if (typeof moduleSource === 'string') {
// Track Lozenge imports
if (LOZENGE_IMPORT_SOURCES.has(moduleSource)) {
node.specifiers.forEach(spec => {
if (spec.type === 'ImportDefaultSpecifier') {
lozengeImports[spec.local.name] = moduleSource;
} else if (spec.type === 'ImportSpecifier' && spec.imported.type === 'Identifier') {
if (spec.imported.name === 'Lozenge') {
lozengeImports[spec.local.name] = moduleSource;
}
}
});
}
// Track Badge imports
if (BADGE_IMPORT_SOURCES.has(moduleSource)) {
node.specifiers.forEach(spec => {
if (spec.type === 'ImportDefaultSpecifier') {
badgeImports[spec.local.name] = moduleSource;
} else if (spec.type === 'ImportSpecifier' && spec.imported.type === 'Identifier') {
if (spec.imported.name === 'Badge' || spec.imported.name === 'default') {
badgeImports[spec.local.name] = moduleSource;
}
}
});
}
// Track legacy Tag imports. The root default remains RemovableTag.
if (isImportFromPackage(moduleSource, '@atlaskit/tag')) {
node.specifiers.forEach(spec => {
if (spec.type === 'ImportDefaultSpecifier') {
// Check for default imports from subpaths and main package
if (SIMPLE_TAG_IMPORT_SOURCES.has(moduleSource)) {
// Default import from @atlaskit/tag/simple-tag is a SimpleTag
tagImports[spec.local.name] = {
type: 'SimpleTag',
source: moduleSource,
node: {
...spec,
parent: node
}
};
} else if (REMOVABLE_TAG_IMPORT_SOURCES.has(moduleSource)) {
// Default import from @atlaskit/tag/removable-tag or @atlaskit/tag is a RemovableTag
tagImports[spec.local.name] = {
type: 'RemovableTag',
source: moduleSource,
node: {
...spec,
parent: node
}
};
}
} else if (spec.type === 'ImportSpecifier' && spec.imported.type === 'Identifier') {
const importName = spec.imported.name;
if (importName === 'SimpleTag' || importName === 'RemovableTag') {
tagImports[spec.local.name] = {
type: importName,
source: moduleSource,
node: {
...spec,
parent: node
}
};
} else if (importName === 'AvatarTag') {
// Track new AvatarTag component - it should not be migrated
newTagImports[spec.local.name] = moduleSource;
}
// Note: Tag from named imports is not skipped - it may still need migration
// (e.g., if it has appearance prop or other old props)
}
});
}
// Track Avatar imports
if (AVATAR_IMPORT_SOURCES.has(moduleSource)) {
node.specifiers.forEach(spec => {
if (spec.type === 'ImportDefaultSpecifier') {
avatarImports[spec.local.name] = moduleSource;
} else if (spec.type === 'ImportSpecifier' && spec.imported.type === 'Identifier') {
if (spec.imported.name === 'Avatar') {
avatarImports[spec.local.name] = moduleSource;
}
}
});
}
}
},
JSXElement(node) {
if (!isNodeOfType(node, 'JSXElement')) {
return;
}
if (!isNodeOfType(node.openingElement.name, 'JSXIdentifier')) {
return;
}
const elementName = node.openingElement.name.name;
// Skip new AvatarTag component - it should not be migrated
if (newTagImports[elementName]) {
return;
}
// Handle SimpleTag, RemovableTag, and Tag migrations
if (tagImports[elementName]) {
const tagImportInfo = tagImports[elementName];
const attributesMap = getAttributesMap(node.openingElement.attributes);
const {
elemBefore: elemBeforeProp,
avatar: avatarProp,
appearance: appearanceProp,
color: colorProp
} = attributesMap;
// Preserve the existing detection scope for root default imports.
if (tagImportInfo.type === 'RemovableTag' && tagImportInfo.source === '@atlaskit/tag') {
// Root avatar-prop consumers are outside this rule's existing migration scope.
if (avatarProp) {
return;
}
// Check if component name is already correct and nothing needs migration
if (elementName === 'Tag' || elementName === 'AvatarTag') {
const needsNameChange = false;
const needsMigration = needsNameChange || appearanceProp || colorNeedsMapping(colorProp);
if (!needsMigration) {
// Still need to check elemBefore for Avatar
if (elemBeforeProp) {
const hasAvatarInElemBefore = getAvatarComponentName(elemBeforeProp) !== null;
if (hasAvatarInElemBefore) {
// Has Avatar in elemBefore, needs migration to AvatarTag
} else {
// No Avatar, nothing to migrate
return;
}
} else {
// No elemBefore, nothing to migrate
return;
}
}
// If we get here, something needs migration
}
}
// Determine migration target based on elemBefore containing Avatar
const hasAvatarInElemBefore = elemBeforeProp ? getAvatarComponentName(elemBeforeProp) !== null : false;
const migration = hasAvatarInElemBefore ? {
reason: 'Choose type="user", "other", or "agent" from the represented entity; automatic inference is unsafe.'
} : getPlainTagFix(node, tagImportInfo);
context.report({
node,
messageId: 'migrateTag',
data: {
remedy: hasAvatarInElemBefore ? "Import AvatarTag from '@atlaskit/tag/avatar-tag'; pass text, type, and avatar={(props) => <Avatar {...props} />}. Preserve non-removability for SimpleTag." : "Import Tag from '@atlaskit/tag/tag-new'; pass text (string or string[]) and use isRemovable={false} for SimpleTag.",
reason: migration.reason
},
fix: 'name' in migration && migration.name ? fixer => {
var _context$sourceCode2;
// @ts-ignore - Jira's ESLint v10 types expose sourceCode, platform still checks with ESLint v9.
const sourceCode = (_context$sourceCode2 = context.sourceCode) !== null && _context$sourceCode2 !== void 0 ? _context$sourceCode2 : context.getSourceCode();
const attributes = node.openingElement.attributes.map(attr => attr.name.name === 'color' ? `color="${mapTagColorValue(extractStringValue(attr.value))}"` : sourceCode.getText(attr));
if (tagImportInfo.type === 'SimpleTag') {
attributes.push('isRemovable={false}');
}
if (!migration.hasTextProp && migration.text !== undefined) {
attributes.push(`text=${JSON.stringify(migration.text)}`);
}
return [fixer.replaceText(tagImportInfo.node.parent, `import ${migration.name} from '@atlaskit/tag/tag-new';`), fixer.replaceText(node, `<${migration.name} ${attributes.join(' ')} />`)];
} : undefined
});
return;
}
// Handle Badge components
if (badgeImports[elementName]) {
// Find the appearance prop
const appearanceProp = node.openingElement.attributes.find(attr => attr.type === 'JSXAttribute' && attr.name.type === 'JSXIdentifier' && attr.name.name === 'appearance');
if (!appearanceProp || appearanceProp.type !== 'JSXAttribute') {
// No appearance prop or it's a spread attribute, nothing to migrate
return;
}
// Check if it's a dynamic expression
if (isDynamicExpression(appearanceProp.value)) {
context.report({
node: appearanceProp,
messageId: 'dynamicBadgeAppearance'
});
return;
}
// Extract the string value
const stringValue = extractStringValue(appearanceProp.value);
if (stringValue && typeof stringValue === 'string') {
const mappedValue = mapBadgeToNewAppearanceValue(stringValue);
if (mappedValue !== stringValue) {
context.report({
node: appearanceProp,
messageId: 'updateBadgeAppearance',
data: {
oldValue: stringValue,
newValue: mappedValue
},
fix: createAppearanceFixer(appearanceProp.value, mappedValue)
});
}
}
return;
}
// Only process if this is a Lozenge component we've imported
if (!lozengeImports[elementName]) {
return;
}
const attributesMap = getAttributesMap(node.openingElement.attributes);
const appearanceProp = attributesMap.appearance;
// Handle appearance prop value migration — always update to new semantic values.
// isBold cleanup is outside this rule; check the installed Lozenge API separately.
if (appearanceProp) {
const stringValue = extractStringValue(appearanceProp.value);
if (stringValue && typeof stringValue === 'string') {
const mappedValue = mapToNewAppearanceValue(stringValue);
if (mappedValue !== stringValue) {
context.report({
node: appearanceProp,
messageId: 'updateAppearance',
data: {
oldValue: stringValue,
newValue: mappedValue
},
fix: createAppearanceFixer(appearanceProp.value, mappedValue)
});
}
}
}
}
};
}
});
export default rule;