@webitel/styleguide 26.8.3 → 26.8.4

package/src/lib/styleguide/token-generation/script/validation/css-var-names.ts

@@ -0,0 +1,40 @@
+import { slugify } from '../transform/slugify';
+import type { Variable } from '../types';
+import { ValidationErrorCollector } from './errors';
+
+/** Validate that no two distinct token paths slugify to the same CSS variable name,
+ * and that no path segment slugifies to an empty string. */
+export function validateCssVarNames(
+	variables: Variable[],
+	fileLabel: string,
+): ValidationErrorCollector {
+	const collector = new ValidationErrorCollector(fileLabel);
+	const byVarName = new Map<string, string[]>();
+
+	for (const variable of variables) {
+		variable.pathSegments.forEach((segment, i) => {
+			if (slugify(segment) === '') {
+				collector.add(
+					`Сегмент шляху "${segment}" за шляхом "${variable.pathSegments.slice(0, i + 1).join('.')}" перетворюється на порожній рядок`,
+					[
+						`Повний шлях: ${variable.pathSegments.join('.')}`,
+					],
+				);
+			}
+		});
+		if (!byVarName.has(variable.cssVarName)) {
+			byVarName.set(variable.cssVarName, []);
+		}
+		byVarName.get(variable.cssVarName)?.push(variable.pathSegments.join('.'));
+	}
+
+	for (const [varName, paths] of byVarName) {
+		if (paths.length > 1) {
+			collector.add(`Колізія назви CSS-змінної: "${varName}"`, [
+				`Створюється ${paths.length} різними шляхами токенів: ${paths.join(', ')}`,
+			]);
+		}
+	}
+
+	return collector;
+}

package/src/lib/styleguide/token-generation/script/validation/errors.ts

@@ -0,0 +1,47 @@
+import { bold, red } from '../console-colors';
+
+interface ValidationError {
+	message: string;
+	details?: string[];
+}
+
+/** A collection of validation errors, each with full contextual detail. */
+export class ValidationErrorCollector {
+	readonly fileLabel: string;
+	readonly errors: ValidationError[] = [];
+
+	constructor(fileLabel: string) {
+		this.fileLabel = fileLabel;
+	}
+
+	add(message: string, details?: string[]): void {
+		this.errors.push({
+			message,
+			details,
+		});
+	}
+
+	get hasErrors(): boolean {
+		return this.errors.length > 0;
+	}
+
+	/** Print all collected errors to the console with full detail, grouped and numbered. */
+	report(): void {
+		console.error(
+			red(
+				bold(
+					`\nПеревірку не пройдено для ${this.fileLabel}: знайдено помилок - ${this.errors.length}:\n`,
+				),
+			),
+		);
+		this.errors.forEach((err, i) => {
+			console.error(red(`${i + 1}) ${err.message}`));
+			if (err.details) {
+				for (const line of err.details) {
+					console.error(red(`   ${line}`));
+				}
+			}
+			console.error('');
+		});
+	}
+}

package/src/lib/styleguide/token-generation/script/validation/parity.ts

@@ -0,0 +1,73 @@
+import type { TokenNode, TokenTree } from '../types';
+import { ValidationErrorCollector } from './errors';
+
+function collectLeafTypes(
+	node: TokenNode,
+	pathSegments: string[],
+	out: Map<string, string>,
+): void {
+	if (node && typeof node === 'object' && '$type' in node) {
+		out.set(
+			pathSegments.join('.'),
+			(
+				node as {
+					$type: string;
+				}
+			).$type,
+		);
+		return;
+	}
+	if (node && typeof node === 'object') {
+		for (const [key, child] of Object.entries(
+			node as Record<string, TokenNode>,
+		)) {
+			if (key.startsWith('$')) continue;
+			collectLeafTypes(child, pathSegments.concat(key), out);
+		}
+	}
+}
+
+/** Validate structural parity between themes: same leaf token paths, same $type per path. */
+export function validateThemeParity(
+	rootsByTheme: Record<string, TokenTree>,
+): ValidationErrorCollector {
+	const collector = new ValidationErrorCollector('узгодженість між темами');
+	const themeNames = Object.keys(rootsByTheme);
+
+	const leavesByTheme: Record<string, Map<string, string>> = {};
+	for (const themeName of themeNames) {
+		const leaves = new Map<string, string>();
+		collectLeafTypes(rootsByTheme[themeName], [], leaves);
+		leavesByTheme[themeName] = leaves;
+	}
+
+	const allPaths = new Set<string>();
+	for (const leaves of Object.values(leavesByTheme)) {
+		for (const p of leaves.keys()) allPaths.add(p);
+	}
+
+	for (const p of allPaths) {
+		const presentIn = themeNames.filter((t) => leavesByTheme[t].has(p));
+		const missingFrom = themeNames.filter((t) => !leavesByTheme[t].has(p));
+		if (missingFrom.length > 0) {
+			collector.add(
+				`Токен "${p}" відсутній у темі(-ах): ${missingFrom.join(', ')}`,
+				[
+					`Присутній у: ${presentIn.join(', ')}`,
+				],
+			);
+			continue;
+		}
+		const types = new Set(themeNames.map((t) => leavesByTheme[t].get(p)));
+		if (types.size > 1) {
+			const detail = themeNames
+				.map((t) => `${t}=${leavesByTheme[t].get(p)}`)
+				.join(', ');
+			collector.add(`Токен "${p}" має різний $type у різних темах`, [
+				detail,
+			]);
+		}
+	}
+
+	return collector;
+}

package/src/lib/styleguide/token-generation/script/validation/references.ts

@@ -0,0 +1,95 @@
+import { getNodeByPath, parseRef } from '../transform/token-refs';
+import type { TokenNode, TokenTree } from '../types';
+import type { ValidationErrorCollector } from './errors';
+
+/** Validate every alias reference in the tree resolves to a real leaf token, and that
+ * following the chain terminates (no circular references). */
+export function validateReferences(
+	root: TokenTree,
+	node: TokenNode,
+	pathSegments: string[],
+	collector: ValidationErrorCollector,
+): void {
+	if (node == null || typeof node !== 'object') return;
+
+	if ('$value' in node) {
+		const value = (
+			node as {
+				$value: unknown;
+			}
+		).$value;
+		if (typeof value === 'string') {
+			const refPath = parseRef(value);
+			if (refPath) {
+				checkReferenceChain(
+					root,
+					refPath,
+					[
+						pathSegments.join('.'),
+					],
+					pathSegments,
+					collector,
+				);
+			}
+		}
+		return;
+	}
+
+	for (const [key, child] of Object.entries(
+		node as Record<string, TokenNode>,
+	)) {
+		if (key.startsWith('$')) continue;
+		validateReferences(root, child, pathSegments.concat(key), collector);
+	}
+}
+
+function checkReferenceChain(
+	root: TokenTree,
+	refPath: string[],
+	chainLabels: string[],
+	originPathSegments: string[],
+	collector: ValidationErrorCollector,
+): void {
+	const refLabel = refPath.join('.');
+	if (chainLabels.includes(refLabel)) {
+		collector.add(
+			`Циклічне посилання за шляхом "${originPathSegments.join('.')}"`,
+			[
+				`Ланцюжок посилань: ${chainLabels.concat(refLabel).join(' -> ')}`,
+			],
+		);
+		return;
+	}
+
+	const target = getNodeByPath(root, refPath);
+	if (!target || typeof target !== 'object' || !('$value' in target)) {
+		collector.add(
+			`Неможливо розв'язати посилання за шляхом "${originPathSegments.join('.')}"`,
+			[
+				`Посилання "{${refLabel}}" не вказує на дійсний токен.`,
+				chainLabels.length > 1
+					? `Ланцюжок посилань до цього моменту: ${chainLabels.join(' -> ')}`
+					: undefined,
+			].filter((line): line is string => Boolean(line)),
+		);
+		return;
+	}
+
+	const targetValue = (
+		target as {
+			$value: unknown;
+		}
+	).$value;
+	if (typeof targetValue === 'string') {
+		const nextRefPath = parseRef(targetValue);
+		if (nextRefPath) {
+			checkReferenceChain(
+				root,
+				nextRefPath,
+				chainLabels.concat(refLabel),
+				originPathSegments,
+				collector,
+			);
+		}
+	}
+}

package/src/lib/styleguide/token-generation/script/validation/theme-file.ts

@@ -0,0 +1,15 @@
+import type { TokenTree } from '../types';
+import { ValidationErrorCollector } from './errors';
+import { validateReferences } from './references';
+import { validateTree } from './tree';
+
+/** Validate one theme file's full token tree (structure + leaves + references). */
+export function validateThemeFile(
+	root: TokenTree,
+	fileLabel: string,
+): ValidationErrorCollector {
+	const collector = new ValidationErrorCollector(fileLabel);
+	validateTree(root, [], collector);
+	validateReferences(root, root, [], collector);
+	return collector;
+}

package/src/lib/styleguide/token-generation/script/validation/tree.ts

@@ -0,0 +1,194 @@
+import { parseRef } from '../transform/token-refs';
+import type { TokenNode } from '../types';
+import type { ValidationErrorCollector } from './errors';
+import { findTypoLikeNames } from './typo-detection';
+
+const SUPPORTED_TYPES = [
+	'color',
+	'number',
+	'string',
+];
+const HEX_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+
+/** Validate the raw token tree structure of a single theme file: every node is either
+ * a group (plain object of children) or a well-formed leaf ({$type, $value, ...}), and
+ * flags sibling group names that look like typos of structural keywords ("Colors"/"Sizes"). */
+export function validateTree(
+	node: TokenNode,
+	pathSegments: string[],
+	collector: ValidationErrorCollector,
+): void {
+	if (node == null || typeof node !== 'object' || Array.isArray(node)) {
+		collector.add(`Некоректний вузол за шляхом "${pathSegments.join('.')}"`, [
+			`Очікувався об'єкт (група або токен), отримано: ${JSON.stringify(node)}`,
+		]);
+		return;
+	}
+
+	const record = node as Record<string, TokenNode>;
+	const childKeys = Object.keys(record).filter((k) => !k.startsWith('$'));
+	const isLeaf = '$type' in record || '$value' in record;
+
+	if (isLeaf) {
+		validateLeaf(record, pathSegments, collector);
+		if (childKeys.length > 0) {
+			collector.add(
+				`Токен має неочікувані вкладені групи за шляхом "${pathSegments.join('.')}"`,
+				[
+					`Вузол із $type/$value має бути кінцевим токеном, але містить вкладені ключі: ${childKeys.join(', ')}`,
+				],
+			);
+		}
+		return;
+	}
+
+	if (childKeys.length === 0) {
+		collector.add(
+			`Порожня група за шляхом "${pathSegments.join('.') || '<корінь>'}"`,
+			[
+				'Група не містить жодних токенів або вкладених груп.',
+			],
+		);
+		return;
+	}
+
+	// Only compare *group* child names against structural keywords - a leaf token
+	// legitimately named "color" or "size" is not a typo of "Colors"/"Sizes".
+	const groupChildKeys = childKeys.filter((key) => {
+		const child = record[key];
+		return (
+			child &&
+			typeof child === 'object' &&
+			!('$type' in child) &&
+			!('$value' in child)
+		);
+	});
+
+	const typoFindings = findTypoLikeNames(groupChildKeys);
+	for (const finding of typoFindings) {
+		collector.add(
+			`Підозріла назва групи "${finding.name}" за шляхом "${pathSegments.concat(finding.name).join('.')}"`,
+			[
+				`Схоже на помилку в написанні "${finding.keyword}" (відстань редагування: ${finding.distance}).`,
+				`Сусідні групи тут: ${groupChildKeys.join(', ')}`,
+				finding.keyword === 'Colors'
+					? 'Папка з назвою "Colors" (без урахування регістру) вважається залежною від теми; помилка в назві призведе до того, що вона мовчки оброблятиметься як незалежна від теми.'
+					: undefined,
+			].filter((line): line is string => Boolean(line)),
+		);
+	}
+
+	for (const key of childKeys) {
+		validateTree(record[key], pathSegments.concat(key), collector);
+	}
+}
+
+/** Validate a single leaf token's $type/$value shape. */
+function validateLeaf(
+	node: Record<string, TokenNode>,
+	pathSegments: string[],
+	collector: ValidationErrorCollector,
+): void {
+	const label = pathSegments.join('.');
+
+	if (!('$value' in node)) {
+		collector.add(`Відсутнє поле $value за шляхом "${label}"`, [
+			`Вузол: ${JSON.stringify(node)}`,
+		]);
+		return;
+	}
+	if (!('$type' in node) || typeof node.$type !== 'string') {
+		collector.add(`Відсутнє або некоректне поле $type за шляхом "${label}"`, [
+			`Вузол: ${JSON.stringify(node)}`,
+		]);
+		return;
+	}
+
+	const type = node.$type as string;
+	const value = node.$value as unknown;
+
+	// Alias references are validated separately (after the whole tree is known), since
+	// resolving them requires looking up other parts of the tree.
+	if (typeof value === 'string' && parseRef(value)) {
+		return;
+	}
+
+	if (!SUPPORTED_TYPES.includes(type)) {
+		collector.add(`Непідтримуваний $type "${type}" за шляхом "${label}"`, [
+			`Підтримувані типи: ${SUPPORTED_TYPES.join(', ')}`,
+			`Значення: ${JSON.stringify(value)}`,
+		]);
+		return;
+	}
+
+	if (type === 'color') {
+		validateColorValue(value, label, collector);
+	} else if (type === 'number') {
+		validateNumberValue(value, label, collector);
+	} else if (type === 'string') {
+		if (typeof value !== 'string') {
+			collector.add(`Некоректне значення типу string за шляхом "${label}"`, [
+				`Очікувався рядок, отримано: ${JSON.stringify(value)}`,
+			]);
+		}
+	}
+}
+
+function validateColorValue(
+	value: unknown,
+	label: string,
+	collector: ValidationErrorCollector,
+): void {
+	if (typeof value === 'string') {
+		// A raw (non-alias) string color, e.g. "#RRGGBB" - allowed by colorToHex().
+		if (!HEX_COLOR_RE.test(value)) {
+			collector.add(`Некоректний рядок кольору за шляхом "${label}"`, [
+				`Очікувався hex-рядок формату "#RRGGBB", отримано: ${JSON.stringify(value)}`,
+			]);
+		}
+		return;
+	}
+	if (!value || typeof value !== 'object') {
+		collector.add(`Некоректне значення кольору за шляхом "${label}"`, [
+			`Очікувався об'єкт із полем "hex", отримано: ${JSON.stringify(value)}`,
+		]);
+		return;
+	}
+	const colorValue = value as {
+		hex?: unknown;
+		alpha?: unknown;
+	};
+	if (
+		typeof colorValue.hex !== 'string' ||
+		!HEX_COLOR_RE.test(colorValue.hex)
+	) {
+		collector.add(`Відсутнє або некоректне поле "hex" за шляхом "${label}"`, [
+			`Очікувалося, що "hex" буде рядком формату "#RRGGBB", отримано: ${JSON.stringify(colorValue.hex)}`,
+		]);
+	}
+	if ('alpha' in colorValue) {
+		const alpha = colorValue.alpha;
+		if (
+			typeof alpha !== 'number' ||
+			Number.isNaN(alpha) ||
+			alpha < 0 ||
+			alpha > 1
+		) {
+			collector.add(`Некоректне поле "alpha" за шляхом "${label}"`, [
+				`Очікувалося число в діапазоні від 0 до 1, отримано: ${JSON.stringify(alpha)}`,
+			]);
+		}
+	}
+}
+
+function validateNumberValue(
+	value: unknown,
+	label: string,
+	collector: ValidationErrorCollector,
+): void {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		collector.add(`Некоректне значення типу number за шляхом "${label}"`, [
+			`Очікувалося скінченне число, отримано: ${JSON.stringify(value)}`,
+		]);
+	}
+}

package/src/lib/styleguide/token-generation/script/validation/typo-detection.ts

@@ -0,0 +1,64 @@
+/** Words that carry structural meaning (drive theme-awareness, grouping, etc.);
+ * a sibling group name that's a near-miss of one of these is almost always a typo. */
+export const STRUCTURAL_KEYWORDS = [
+	'Colors',
+	'Sizes',
+];
+
+export interface TypoFinding {
+	name: string;
+	keyword: string;
+	distance: number;
+}
+
+/** Levenshtein edit distance between two strings (case-insensitive). */
+export function editDistance(a: string, b: string): number {
+	a = a.toLowerCase();
+	b = b.toLowerCase();
+	const dp: number[][] = Array.from(
+		{
+			length: a.length + 1,
+		},
+		(_, i) =>
+			[
+				i,
+			].concat(Array(b.length).fill(0)),
+	);
+	for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+	for (let i = 1; i <= a.length; i++) {
+		for (let j = 1; j <= b.length; j++) {
+			dp[i][j] =
+				a[i - 1] === b[j - 1]
+					? dp[i - 1][j - 1]
+					: 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+		}
+	}
+	return dp[a.length][b.length];
+}
+
+/** Detect group names among `names` that look like typos of a structural keyword
+ * (close edit distance, but not an exact/case-insensitive match). Only meant to be
+ * called with the names of *group* children (never leaf token names) - "color" or
+ * "size" as an actual property name is common and not a typo of "Colors"/"Sizes". */
+export function findTypoLikeNames(names: string[]): TypoFinding[] {
+	const findings: TypoFinding[] = [];
+	for (const name of names) {
+		for (const keyword of STRUCTURAL_KEYWORDS) {
+			if (name.toLowerCase() === keyword.toLowerCase()) continue;
+			const distance = editDistance(name, keyword);
+			if (
+				distance > 0 &&
+				distance <= 2 &&
+				Math.abs(name.length - keyword.length) <= 2
+			) {
+				findings.push({
+					name,
+					keyword,
+					distance,
+				});
+				break;
+			}
+		}
+	}
+	return findings;
+}