bitboss-ui 3.0.0-beta.5 → 3.0.0-beta.50

package/scripts/lib/redundant-item-accessor.mjs

@@ -0,0 +1,398 @@
+/**
+ * `redundant-item-accessor` (Q60.24, owner 2026-10-07): with no `item-text`
+ * an option reads its own `label`, else its own `text`; with no `item-value`
+ * its own `value`. An accessor that names exactly that field restates the
+ * default and is cruft: `item-text="label"`, `item-text="text"`,
+ * `item-value="value"` (static or `:item-text="'label'"`, kebab or camel) on
+ * the option surfaces, and `itemText: 'label'` / `'text'` /
+ * `itemValue: 'value'` in a BbDropdown group.
+ *
+ * Reported only when removing it cannot change what renders:
+ * - `item-text="label"` / `item-value="value"`: when the items are not
+ *   visible in the file (the field is assumed present), or when every visible
+ *   item is an object literal spelling that field. A primitive item or an
+ *   object without the field reads differently through the default.
+ * - `item-text="text"`: only when every visible item spells `text` and none
+ *   spells `label` or spreads (`label` would win over `text`); never on items
+ *   the file cannot see.
+ * - A dropdown group stays a mapped group after the removal: its `items` is a
+ *   function, or it keeps `itemProps`, `max` or another mapper. A group whose
+ *   only mapper is the redundant one would turn into a hand-written group.
+ *
+ * The ESLint twin is `bitboss-ui/no-redundant-item-accessor`
+ * (eslint-plugin.mjs): both read the findings below; each carries the range
+ * the autofix deletes.
+ */
+import { babelParse, parse } from 'vue/compiler-sfc';
+import { libraryAliases, localBbImports } from './local-components.mjs';
+
+const NODE_ELEMENT = 1;
+const PROP_ATTRIBUTE = 6;
+const PROP_DIRECTIVE = 7;
+
+/** The components whose options read the default chain. */
+export const ACCESSOR_SURFACES = new Set([
+	'BbSelect',
+	'BbSelectPopover',
+	'BbRadioGroup',
+	'BbCheckboxGroup',
+	'BbSwitchGroup',
+]);
+
+/** Hosts whose `items` hold BbDropdown groups. */
+const DROPDOWN_HOSTS = new Set(['BbDropdown', 'BbDropdownButton']);
+
+/** accessor → the field values that restate its default. */
+const DEFAULT_FIELDS = { itemText: ['label', 'text'], itemValue: ['value'] };
+
+export const REDUNDANT_ACCESSOR_MESSAGES = {
+	attr: (attr, field) =>
+		`\`${attr}\` restates the default: ${
+			field === 'value'
+				? "an option's value is its own `value`"
+				: 'an option reads its own `label`, else its own `text`'
+		}. Remove it.`,
+	group: (prop, field) =>
+		`\`${prop}: '${field}'\` restates the group's default: ${
+			field === 'value'
+				? "a row's value is its own `value`"
+				: 'a row reads its own `label`, else its own `text`'
+		}. Remove it.`,
+};
+
+export const REDUNDANT_ACCESSOR_HINT =
+	'`{ label, value }` and `{ text, value }` items work as they are; an accessor is only for another shape';
+
+const pascal = (tag) =>
+	tag.includes('-')
+		? tag.replace(/(?:^|-)([a-z0-9])/g, (_, c) => c.toUpperCase())
+		: tag;
+
+const camel = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+const unwrap = (node) => {
+	let current = node;
+	while (
+		current &&
+		[
+			'TSAsExpression',
+			'TSSatisfiesExpression',
+			'TSNonNullExpression',
+			'TSTypeAssertion',
+			'ParenthesizedExpression',
+		].includes(current.type)
+	)
+		current = current.expression;
+	return current;
+};
+
+const keyName = (property) =>
+	(property.type === 'ObjectProperty' || property.type === 'ObjectMethod') &&
+	!property.computed
+		? property.key.type === 'Identifier'
+			? property.key.name
+			: property.key.type === 'StringLiteral'
+				? property.key.value
+				: undefined
+		: undefined;
+
+const propertyOf = (object, key) =>
+	object.properties.find((p) => keyName(p) === key);
+
+/** A string literal (`'label'`, `"label"`, `` `label` ``) → its value. */
+const stringValue = (node) => {
+	const value = unwrap(node);
+	if (value?.type === 'StringLiteral') return value.value;
+	if (
+		value?.type === 'TemplateLiteral' &&
+		value.expressions.length === 0 &&
+		value.quasis.length === 1
+	)
+		return value.quasis[0].value.cooked;
+	return undefined;
+};
+
+/**
+ * The visible items of an array: `null` when the array cannot be judged
+ * (not in the file, or mutated), else one entry per element —
+ * `{ keys, spread }` for an object literal, `null` for anything else.
+ */
+const shapeOf = (arrayNode) =>
+	arrayNode
+		? arrayNode.elements.map((raw) => {
+				const element = unwrap(raw);
+				if (element?.type !== 'ObjectExpression') return null;
+				return {
+					keys: new Set(element.properties.map(keyName).filter(Boolean)),
+					spread: element.properties.some((p) => p.type === 'SpreadElement'),
+				};
+			})
+		: null;
+
+/**
+ * Whether `accessor = field` restates the default for items of this shape.
+ * @param {'itemText' | 'itemValue'} accessor
+ * @param {string} field
+ * @param {null | Array<null | { keys: Set<string>, spread: boolean }>} shape
+ */
+export function restatesDefault(accessor, field, shape) {
+	if (!DEFAULT_FIELDS[accessor]?.includes(field)) return false;
+	if (accessor === 'itemText' && field === 'text') {
+		if (!shape) return false;
+		return shape.every(
+			(item) =>
+				item && !item.spread && !item.keys.has('label') && item.keys.has('text')
+		);
+	}
+	if (!shape) return true;
+	return shape.every((item) => item && item.keys.has(field));
+}
+
+/** Resolves an `items` expression to an ArrayExpression, or null. */
+const arrayOf = (node, arrays) => {
+	const value = unwrap(node);
+	if (value?.type === 'ArrayExpression') return value;
+	if (value?.type === 'Identifier' && !arrays?.mutated?.has(value.name))
+		return arrays?.get(value.name) ?? null;
+	return null;
+};
+
+/** The range to delete with an attribute: it and the whitespace before it. */
+const attrRemoval = (code, start, end) => {
+	let from = start;
+	while (from > 0 && /\s/.test(code[from - 1])) from--;
+	return [from, end];
+};
+
+/** The range to delete with an object property: it and one comma. */
+const propertyRemoval = (code, start, end) => {
+	let to = end;
+	while (to < code.length && /[ \t]/.test(code[to])) to++;
+	if (code[to] === ',') {
+		to++;
+		// Alone on its line: take the whole line.
+		let lineStart = start;
+		while (lineStart > 0 && /[ \t]/.test(code[lineStart - 1])) lineStart--;
+		let after = to;
+		while (after < code.length && /[ \t]/.test(code[after])) after++;
+		if (
+			(lineStart === 0 || code[lineStart - 1] === '\n') &&
+			code[after] === '\n'
+		)
+			return [lineStart, after + 1];
+		while (to < code.length && /[ \t]/.test(code[to])) to++;
+		return [start, to];
+	}
+	// The last property: take the comma before it.
+	let from = start;
+	while (from > 0 && /\s/.test(code[from - 1])) from--;
+	if (code[from - 1] === ',') from--;
+	return [from, end];
+};
+
+const parseExpression = (content) => {
+	try {
+		const program = babelParse(`(${content})`, {
+			sourceType: 'module',
+			plugins: ['typescript'],
+		}).program;
+		return program.body[0]?.expression ?? null;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * @param {string} code a whole SFC (ranges are offsets into it) or a snippet
+ * @param {{ templateAst?: any, arrays?: Map<string, any> & { mutated?: Set<string> }, library?: Parameters<typeof localBbImports>[1] }} [options]
+ *   `arrays`: the file's script-setup array consts (`scriptSetupArrayConsts`)
+ *   `library`: what counts as the library besides `bitboss-ui` (`isLibrarySource`)
+ * @returns {Array<{ component: string, attr: string, kind: 'redundant-item-accessor', line: number, message: string, hint: string, severity: 'warning', range?: [number, number], edit?: { range: [number, number], text: string } }>}
+ *   `edit` is the autofix as a text replacement (a deletion is `text: ''`), so a
+ *   later finding can rewrite instead of delete without touching the rule
+ */
+export function redundantItemAccessorFindings(code, options = {}) {
+	if (!/item-?(text|value)|itemText|itemValue/i.test(code)) return [];
+	let descriptor = null;
+	try {
+		({ descriptor } = parse(code, { sourceMap: false }));
+	} catch {
+		descriptor = null;
+	}
+	const ast = options.templateAst ?? descriptor?.template?.ast;
+	if (!ast) return [];
+	// Offsets are only trusted on the file's own template AST.
+	const ranged =
+		!options.templateAst || options.templateAst === descriptor?.template?.ast;
+	const arrays = options.arrays;
+	const aliases = libraryAliases(code);
+	const own = localBbImports(code, options.library);
+	const scriptOffset = descriptor?.scriptSetup?.loc.start.offset ?? 0;
+	const scriptLine = descriptor?.scriptSetup?.loc.start.line ?? 1;
+	const findings = [];
+
+	const itemsShape = (element) => {
+		for (const prop of element.props ?? []) {
+			if (prop.type !== PROP_DIRECTIVE || prop.name !== 'bind') continue;
+			if (!prop.arg?.isStatic || prop.arg.content !== 'items') continue;
+			const expression = parseExpression(prop.exp?.content ?? '');
+			return shapeOf(arrayOf(expression, arrays));
+		}
+		return null;
+	};
+
+	const checkSurface = (element, component) => {
+		let shape;
+		for (const prop of element.props ?? []) {
+			let name;
+			let field;
+			if (prop.type === PROP_ATTRIBUTE) {
+				name = camel(prop.name);
+				field = prop.value?.content;
+			} else if (
+				prop.type === PROP_DIRECTIVE &&
+				prop.name === 'bind' &&
+				prop.arg?.isStatic
+			) {
+				name = camel(prop.arg.content);
+				if (!(name in DEFAULT_FIELDS)) continue;
+				field = stringValue(parseExpression(prop.exp?.content ?? ''));
+			}
+			if (!(name in DEFAULT_FIELDS) || field === undefined) continue;
+			shape ??= itemsShape(element);
+			if (!restatesDefault(name, field, shape)) continue;
+			const attr = code.slice(prop.loc.start.offset, prop.loc.end.offset);
+			findings.push({
+				component,
+				attr: prop.type === PROP_ATTRIBUTE ? prop.name : `:${prop.arg.content}`,
+				kind: 'redundant-item-accessor',
+				line: prop.loc.start.line,
+				message: REDUNDANT_ACCESSOR_MESSAGES.attr(
+					ranged ? attr : `${prop.name}="${field}"`,
+					field
+				),
+				hint: REDUNDANT_ACCESSOR_HINT,
+				severity: 'warning',
+				...(ranged
+					? {
+							range: [prop.loc.start.offset, prop.loc.end.offset],
+							edit: {
+								range: attrRemoval(
+									code,
+									prop.loc.start.offset,
+									prop.loc.end.offset
+								),
+								text: '',
+							},
+						}
+					: {}),
+			});
+		}
+	};
+
+	/** Groups inside a host's `items` array (script-side or inline). */
+	const checkGroups = (array, component, base) => {
+		for (const raw of array.elements) {
+			const entry = unwrap(raw);
+			if (entry?.type !== 'ObjectExpression') continue;
+			const itemsProp = propertyOf(entry, 'items');
+			const itemsValue =
+				itemsProp?.type === 'ObjectMethod'
+					? itemsProp
+					: unwrap(itemsProp?.value);
+			const isFunction =
+				itemsValue?.type === 'ObjectMethod' ||
+				itemsValue?.type === 'ArrowFunctionExpression' ||
+				itemsValue?.type === 'FunctionExpression';
+			const childArray = isFunction ? null : arrayOf(itemsValue, arrays);
+			const shape = isFunction ? null : shapeOf(childArray);
+			const mappers = ['itemText', 'itemValue']
+				.map((name) => ({ name, property: propertyOf(entry, name) }))
+				.filter((m) => m.property);
+			const redundant = mappers.filter(({ name, property }) => {
+				if (property.type !== 'ObjectProperty') return false;
+				const field = stringValue(property.value);
+				return field !== undefined && restatesDefault(name, field, shape);
+			});
+			const staysMapped =
+				isFunction ||
+				!!propertyOf(entry, 'itemProps') ||
+				!!propertyOf(entry, 'max') ||
+				mappers.length > redundant.length;
+			// An `items` identifier the file cannot see may be a function, or not.
+			if (redundant.length && staysMapped) {
+				for (const { name, property } of redundant) {
+					const field = stringValue(property.value);
+					findings.push({
+						component,
+						attr: name,
+						kind: 'redundant-item-accessor',
+						line: base.line + property.loc.start.line - 1,
+						message: REDUNDANT_ACCESSOR_MESSAGES.group(name, field),
+						hint: REDUNDANT_ACCESSOR_HINT,
+						severity: 'warning',
+						...(base.offset !== null
+							? {
+									range: [
+										base.offset + property.start,
+										base.offset + property.end,
+									],
+									edit: {
+										range: propertyRemoval(
+											code,
+											base.offset + property.start,
+											base.offset + property.end
+										),
+										text: '',
+									},
+								}
+							: {}),
+					});
+				}
+			}
+			if (childArray) checkGroups(childArray, component, base);
+		}
+	};
+
+	const seenArrays = new Set();
+	const checkHost = (element, component) => {
+		for (const prop of element.props ?? []) {
+			if (prop.type !== PROP_DIRECTIVE || prop.name !== 'bind') continue;
+			if (!prop.arg?.isStatic || prop.arg.content !== 'items') continue;
+			const content = prop.exp?.content ?? '';
+			const expression = parseExpression(content);
+			const value = unwrap(expression);
+			if (value?.type === 'Identifier') {
+				const array = arrayOf(value, arrays);
+				// A script const bound by two hosts is reported once.
+				if (!array || seenArrays.has(array)) continue;
+				seenArrays.add(array);
+				checkGroups(array, component, {
+					offset: ranged && descriptor?.scriptSetup ? scriptOffset : null,
+					line: scriptLine,
+				});
+			} else if (value?.type === 'ArrayExpression') {
+				// `(` was prepended to the expression before parsing.
+				const start = prop.exp.loc.start.offset - 1;
+				checkGroups(value, component, {
+					offset: ranged ? start : null,
+					line: prop.exp.loc.start.line,
+				});
+			}
+		}
+	};
+
+	const walk = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (node.type === NODE_ELEMENT && !own.has(node.tag)) {
+			const written = pascal(node.tag);
+			const component =
+				aliases.get(node.tag) ?? aliases.get(written) ?? written;
+			if (ACCESSOR_SURFACES.has(component)) checkSurface(node, component);
+			if (DROPDOWN_HOSTS.has(component)) checkHost(node, component);
+		}
+		for (const child of node.children ?? []) walk(child);
+	};
+	walk(ast);
+	return findings;
+}