@public-ui/visual-tests 1.7.0-rc.6 → 1.7.0-rc.8

package/README.md

@@ -1,47 +1,168 @@
-# KoliBri - Visual Tests
+# KoliBri - CLI-Tools
 
 ## Motivation
 
-The `KoliBri` Visual Tests provide a way to add visual regression testing to **theme** modules.  
-It takes screenshots of every component defined in the [React Sample App](https://github.com/public-ui/kolibri/tree/develop/packages/samples/react) with the theme applied and compares them to their references.
+The `KoliBri` CLI-Tools are a collection of tools to support the development with `KoliBri` components.
 
 ## Installation
 
-You can install the `KoliBri` Visual Tests with `npm`, `pnpm` or `yarn`:
+You can install the `KoliBri` CLI-Tools with `npm`, `pnpm` or `yarn`.
 
 ```bash
-npm i -D @public-ui/visual-tests
-pnpm i -D @public-ui/visual-tests
-yarn add -D @public-ui/visual-tests
+npm i -g @public-ui/kolibri-cli
+pnpm i -g @public-ui/kolibri-cli
+yarn add -g @public-ui/kolibri-cli
 ```
 
 ## Usage
 
-Add the following npm scripts to the theme's `package.json`:
+The `KoliBri` CLI is intended to be executed in your project root directory. Use the `kolibri` command to start the CLI.
 
-```json
-{
-	"scripts": {
-		"test": "THEME_MODULE=src/index THEME_EXPORT=THEME_NAME kolibri-visual-test",
-		"test-update": "THEME_MODULE=src/index THEME_EXPORT=THEME_NAME kolibri-visual-test --update-snapshots"
-	}
-}
+```bash
+kolibri --help
+```
+
+```bash
+,--. ,--.         ,--. ,--. ,-----.           ,--.
+|  .'   /  ,---.  |  | `--' |  |) /_  ,--.--. `--'
+|  .   '  | .-. | |  | ,--. |  .-.  \ |  .--' ,--.
+|  |\   \ | '-' | |  | |  | |  '--' / |  |    |  |
+`--' `--´  `---´  `--' `--' `------´  `--'    `--'
+🚹 The accessible HTML-Standard | 👉 https://public-ui.github.io
+
+Usage: kolibri [options] [command]
+
+CLI for executing some helpful commands for KoliBri projects.
+
+Options:
+  -V, --version               output the version number
+  -h, --help                  display help for command
+
+Commands:
+  migrate [options] <string>  This command migrates KoliBri code to the current version.
+  help [command]              display help for command
+```
+
+### Migrate
+
+With the `migrate` command you can migrate your project to the latest version of `KoliBri`.
+
+Actually the following migrations are available:
+
+- Component renaming ✓
+- Component removal ⏰
+- Property renaming ✓
+- Property removal ✓
+- Property type change ⏰
+- Logic refactoring ⏰
+- Expert-Slot refactoring ⏰
+- `.vscode/settings.json` add IntelliSense for HTML ⏰
+- `.gitignore` exclude `.kolibri.migrate.json` ⏰
+- `.tsconfig` add `@public-ui/components` to `types` array ⏰
+
+#### How does it work?
+
+1. The migration command will check your project for clear `git history` and the `installed version` of `KoliBri`. Now it loads all available migration tasks.
+2. Tasks in the correct version range will be executed one by one. Otherwise they will be skipped.
+3. After that the `package.json` will be updated with the new version of `KoliBri` and execute the `npm install` command.
+4. If there are any pending tasks, the migration command will be executed again. Otherwise the migration is finished.
+5. Now you can check the result and commit the changes.
+
+> **Note:** You can reset the migration with `git reset --hard HEAD~1` or by discarding the affected files.
+
+#### Help
+
+```bash
+kolibri migrate --help
+```
+
+#### Execute
+
+```bash
+kolibri migrate <path>
 ```
 
-- `THEME_MODULE` defines the relative path to the TypeScript module containing the the theme definitions. Without file extension.
-- `THEME_EXPERT` defines the name of the export within the the module. (e.g., `export const THEME_NAME = {/**/};`) Defaults to `default`.
+#### Options
 
-Run the tests with `npm test`. The first time, this will create a new folder `snapshots` which is supposed to be committed to the repository.
-In the following runs, new screenshots will be compared to this reference.
+| Option                         | Description                               |         Type         | Default  |
+| ------------------------------ | ----------------------------------------- | :------------------: | :------: |
+| `--ignore-uncommitted-changes` | Allows execution with uncommitted changes |       boolean        |  false   |
+| `--remove-mode`                | Prefix property name or delete property   | `delete` \| `prefix` | `prefix` |
 
-To update the reference screenshots call `npm run test-update`.
+#### Configuration
 
-It's also recommended to automatically run the tests before packing/publishing the module:
+You can configure the migration with the `.kolibri.config.json` file in your project root folder. This file will be created automatically after the first migration.
+
+**Troubleshooting:** If you have problems with migration, you can exclude some tasks with the configuration by setting the `false` flag (see `kol-select`).
 
 ```json
 {
-	"scripts": {
-		"prepack": "npm test"
+	"migrate": {
+		"tasks": {
+			"kol-abbr-rename-property-_title-to-_label": true,
+			"kol-accordion-rename-property-_heading-to-_label": true,
+			"kol-badge-rename-property-_icon-only-to-_hide-label": true,
+			"kol-badge-remove-property-_hide-label": true,
+			"kol-badge-remove-property-_icon-only": true,
+			"kol-breadcrumb-rename-property-_aria-label-to-_label": true,
+			"kol-button-link-remove-property-_aria-current": true,
+			"kol-button-link-remove-property-_aria-label": true,
+			"kol-button-link-rename-property-_icon-only-to-_hide-label": true,
+			"kol-button-remove-property-_aria-current": true,
+			"kol-button-remove-property-_aria-label": true,
+			"kol-button-rename-property-_icon-only-to-_hide-label": true,
+			"kol-card-rename-property-_heading-to-_label": true,
+			"kol-card-rename-property-_headline-to-_label": true,
+			"kol-details-rename-property-_summary-to-_label": true,
+			"kol-icon-remove-property-_part": true,
+			"kol-icon-rename-property-_aria-label-to-_label": true,
+			"kol-checkbox-rename-property-_type-to-_variant": true,
+			"kol-color-rename-property-_list-to-_suggestions": true,
+			"kol-date-rename-property-_list-to-_suggestions": true,
+			"kol-input-email-rename-property-_list-to-_suggestions": true,
+			"kol-input-number-rename-property-_list-to-_suggestions": true,
+			"kol-input-radio-rename-property-_list-to-_options": true,
+			"kol-input-range-rename-property-_list-to-_suggestions": true,
+			"kol-input-text-rename-property-_list-to-_suggestions": true,
+			"kol-link-group-rename-property-_aria-label-to-_label": true,
+			"kol-link-group-remove-property-_ordered": true,
+			"kol-nav-rename-property-_aria-label-to-_label": true,
+			"kol-nav-rename-property-_compact-to-_hide-label": true,
+			"kol-nav-remove-property-_has-compact-button": true,
+			"kol-pagination-rename-property-_count-to-_total": true,
+			"kol-progress-rename-property-_type-to-_variant": true,
+			"kol-quote-rename-property-_caption-to-_label": true,
+			"kol-select-rename-property-_height-to-_rows": false,
+			"kol-select-rename-property-_list-to-_options": false,
+			"kol-skip-nav-rename-property-_aria-label-to-_label": true,
+			"kol-span-rename-property-_icon-only-to-_hide-label": true,
+			"kol-split-button-remove-property-_aria-label": true,
+			"kol-table-rename-property-_caption-to-_label": true,
+			"kol-tabs-rename-property-_aria-label-to-_label": true,
+			"kol-tabs-rename-property-_tab-align-to-_align": true,
+			"kol-toast-rename-property-_heading-to-_label": true,
+			"kol-version-rename-property-_version-to-_label": true
+		}
 	}
 }
 ```
+
+## Troubleshooting
+
+If the migration failed, you can reset the migration with `git reset --hard HEAD~1`.
+
+Use the configuration (`.kolibri.config.json`) to exclude some tasks.
+
+If there are multiple obsolete properties that have been migrated to just one new property, the new property may appear multiple times in the tag. You can then decide which variant to use and remove all other variants accordingly.
+
+Maybe it can help to prepare your code in the tricky places for migration.
+
+Please give us feedback, if you have problems with the migration: [GitHub Issues](https://github.com/public-ui/kolibri/issues/new?assignees=&labels=useful+hint&projects=&template=7_feedback.md&title=%F0%9F%92%A1+CLI%3A+)
+
+## Dry run
+
+You have always the possibility of a dry run. Because before the migration will be executed, you need a clean git history of you project.
+
+After the migration you can check the result with `git status` and `git diff`.
+
+Is anything wrong, you can reset the migration with `git reset --hard HEAD~1` or by discarding the affected files.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@public-ui/visual-tests",
-	"version": "1.7.0-rc.6",
+	"version": "1.7.0-rc.8",
 	"license": "EUPL-1.2",
 	"homepage": "https://public-ui.github.io",
 	"repository": "https://github.com/public-ui/kolibri",
@@ -16,33 +16,31 @@
 	"sideEffects": false,
 	"description": "Provides utility to run visual regression tests for themes.",
 	"scripts": {
-		"build": "tsc --outDir dist",
+		"depcheck": "depcheck --ignores=@public-ui/sample-react,http-server,tslib",
 		"format": "prettier --check src",
-		"lint": "eslint src && tsc --noemit",
-		"unused": "knip",
-		"prepare": "npm run build"
+		"lint": "eslint src",
+		"unused": "knip"
 	},
 	"bin": {
-		"kolibri-visual-test": "kolibri-visual-test.sh"
-	},
-	"devDependencies": {
-		"@types/node": "20.6.0",
-		"@typescript-eslint/eslint-plugin": "6.7.0",
-		"eslint": "8.49.0",
-		"eslint-plugin-no-loops": "0.3.0",
-		"knip": "2.23.0",
-		"npm-check-updates": "16.13.3",
-		"prettier": "3.0.3",
-		"tslib": "2.6.2",
-		"typescript": "5.2.2"
+		"kolibri-visual-test": "src/index.js"
 	},
 	"dependencies": {
 		"@playwright/test": "1.37.1",
-		"@public-ui/sample-react": "1.7.0-rc.6",
+		"@public-ui/sample-react": "1.7.0-rc.8",
 		"http-server": "14.1.1",
 		"portfinder": "1.0.32"
 	},
+	"devDependencies": {
+		"@babel/eslint-parser": "7.22.15",
+		"depcheck": "1.4.6",
+		"eslint": "8.49.0",
+		"eslint-plugin-no-loops": "0.3.0",
+		"knip": "2.24.0",
+		"prettier": "3.0.3"
+	},
 	"files": [
-		"dist"
+		"playwright.config.js",
+		"src",
+		"tests"
 	]
 }

package/src/index.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import gradient from 'gradient-string';
+
+import migrate from './migrate';
+import { getVersionOfPublicUiKoliBriCli } from './migrate/shares/reuse';
+
+const versionOfPublicUiKoliBriCli = getVersionOfPublicUiKoliBriCli();
+
+const banner = gradient.atlas.multiline(
+	`
+,--. ,--.         ,--. ,--. ,-----.           ,--.
+|  .'   /  ,---.  |  | \`--' |  |) /_  ,--.--. \`--'
+|  .   '  | .-. | |  | ,--. |  .-.  \\ |  .--' ,--.
+|  |\\   \\ | '-' | |  | |  | |  '--' / |  |    |  |
+\`--' \`--´  \`---´  \`--' \`--' \`------´  \`--'    \`--'
+🚹 The accessible HTML-Standard | 👉 https://public-ui.github.io | ${versionOfPublicUiKoliBriCli}
+`,
+	{
+		interpolation: 'hsv',
+	},
+);
+console.log(banner);
+
+const program = new Command();
+
+program.name('kolibri').description('CLI for executing some helpful commands for KoliBri projects.').version(versionOfPublicUiKoliBriCli);
+
+// Add commands
+migrate(program);
+
+program.parse();

package/src/migrate/index.ts

@@ -0,0 +1,127 @@
+import { exec } from 'child_process';
+import { Command, Option } from 'commander';
+import fs from 'fs';
+import path from 'path';
+
+import { Configuration } from '../types';
+import { TaskRunner } from './runner/task-runner';
+import { testTasks } from './runner/tasks/test';
+import { v1Tasks } from './runner/tasks/v1';
+import {
+	getContentOfProjectPkgJson,
+	getPackageManagerInstallCommand,
+	getVersionOfPublicUiComponents,
+	getVersionOfPublicUiKoliBriCli,
+	logAndCreateError,
+	MODIFIED_FILES,
+	setRemoveMode,
+} from './shares/reuse';
+import { REMOVE_MODE, RemoveMode } from './types';
+
+type MigrateOption = {
+	ignoreUncommittedChanges: boolean;
+	removeMode: RemoveMode;
+	testTasks: boolean;
+};
+
+/**
+ * This function is used to register the migrate command.
+ * @param {Command} program The program object to register the command
+ */
+export default function (program: Command): void {
+	program
+		.command('migrate')
+		.description('This command migrates KoliBri code to the current version.')
+		.argument('[string]', 'Source code folder to migrate', 'src')
+		.addOption(new Option('--ignore-uncommitted-changes', 'Allows execution with uncommitted changes').default(false))
+		.addOption(new Option('--remove-mode <mode>', 'Prefix property name or delete property').choices(REMOVE_MODE).default('prefix'))
+		.addOption(new Option('--test-tasks', 'Run additional test tasks').default(false).hideHelp())
+		.action((baseDir: string, options: MigrateOption) => {
+			exec('git status --porcelain', (err, stdout) => {
+				if (err) {
+					console.error(`exec error: ${err.message}`);
+					return;
+				}
+
+				if (!options.ignoreUncommittedChanges && stdout) {
+					throw logAndCreateError('There are uncommitted changes');
+				}
+
+				setRemoveMode(options.removeMode);
+
+				const versionOfPublicUiComponents = getVersionOfPublicUiComponents();
+				const versionOfPublicUiKoliBriCli = getVersionOfPublicUiKoliBriCli();
+
+				console.log(`
+Current version of @public-ui/components: ${versionOfPublicUiComponents}
+Source folder to migrate: ${baseDir}
+`);
+
+				const configFile = path.resolve(process.cwd(), '.kolibri.config.json');
+				let config: Configuration = {};
+				if (fs.existsSync(configFile)) {
+					try {
+						config = JSON.parse(fs.readFileSync(configFile, 'utf8')) as Configuration;
+					} catch (e) {
+						// ignore
+					}
+				}
+
+				const runner = new TaskRunner(baseDir, versionOfPublicUiKoliBriCli, versionOfPublicUiComponents, config);
+				runner.registerTasks(v1Tasks);
+
+				if (options.testTasks) {
+					runner.registerTasks(testTasks);
+				}
+
+				let version = versionOfPublicUiComponents;
+
+				/**
+				 * Runs the task runner in a loop until all tasks are completed.
+				 */
+				function runLoop() {
+					runner.run();
+					if (version !== runner.getPendingMinVersion()) {
+						version = runner.getPendingMinVersion();
+						let packageJson = getContentOfProjectPkgJson();
+						packageJson = packageJson.replace(/"(@public-ui\/[^"]+)":\s*".*"/g, `"$1": "${version}"`);
+						fs.writeFileSync(path.resolve(process.cwd(), 'package.json'), packageJson);
+						runner.setProjectVersion(version);
+
+						console.log(`- Update @public-ui/* to version ${version}`);
+						exec(getPackageManagerInstallCommand(), (err) => {
+							if (err) {
+								console.error(`exec error: ${err.message}`);
+								return;
+							}
+							runLoop();
+						});
+					} else {
+						console.log(`
+Status of all executed Tasks:`);
+
+						const status = runner.getStatus(true);
+						fs.writeFileSync(configFile, JSON.stringify(status.config, null, 2));
+
+						console.log(`
+Modified files: ${MODIFIED_FILES.size}`);
+						MODIFIED_FILES.forEach((file) => {
+							console.log(`- ${file}`);
+						});
+
+						console.log(`
+After the code migration has gone through, the code formatting may no longer be as desired. Therefore, please reformat your code afterwards if necessary.
+
+Afterwards, it may be that functions or themes in newer major versions have changed or are no longer included. This should be checked finally and corrected manually if necessary.
+
+Is anything wrong, you can reset the migration with "git reset --hard HEAD~1" or by discarding the affected files. For more information read the troubleshooting section in the README.`);
+					}
+				}
+
+				const status = runner.getStatus();
+				console.log(`
+Execute ${status.total} registered tasks...`);
+				runLoop();
+			});
+		});
+}

package/src/migrate/runner/abstract-task.ts

@@ -0,0 +1,64 @@
+import semver from 'semver';
+
+import { FILE_EXTENSIONS, FileExtension } from '../../types';
+import { logAndCreateError } from '../shares/reuse';
+import { TaskStatus } from './types';
+
+export type TaskOptions = {
+	dependentTasks?: AbstractTask[];
+	description?: string;
+};
+
+export abstract class AbstractTask {
+	private status: TaskStatus = 'pending';
+
+	protected static readonly instances: Map<string, AbstractTask> = new Map();
+
+	protected readonly description?: string;
+
+	protected constructor(
+		protected readonly identifier: string,
+		protected readonly title: string,
+		protected readonly extensions: FileExtension[],
+		protected readonly versionRange: string,
+		protected readonly dependentTasks: AbstractTask[] = [],
+		options: TaskOptions = {},
+	) {
+		this.description = options.description;
+		this.extensions = this.extensions.filter((ext) => FILE_EXTENSIONS.includes(ext));
+
+		if (!semver.validRange(this.versionRange)) {
+			throw logAndCreateError(`[${this.identifier}] Invalid semver range version: ${this.versionRange}`);
+		}
+	}
+
+	public getDependentTasks(): AbstractTask[] {
+		return this.dependentTasks;
+	}
+
+	public getDescription(): string | undefined {
+		return this.description;
+	}
+
+	public getIdentifier(): string {
+		return this.identifier;
+	}
+
+	public setStatus(status: TaskStatus): void {
+		this.status = status;
+	}
+
+	public getStatus(): TaskStatus {
+		return this.status;
+	}
+
+	public getTitle(): string {
+		return this.title;
+	}
+
+	public getVersionRange(): string {
+		return this.versionRange;
+	}
+
+	public abstract run(baseDir: string): void;
+}

package/src/migrate/runner/task-runner.ts

@@ -0,0 +1,163 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import semver from 'semver';
+
+import { Configuration } from '../../types';
+import { logAndCreateError } from '../shares/reuse';
+import { AbstractTask } from './abstract-task';
+
+export class TaskRunner {
+	private readonly tasks: Map<string, AbstractTask> = new Map();
+	private baseDir: string = '/';
+	private cliVersion: string = '0.0.0';
+	private projectVersion: string = '0.0.0';
+	private readonly config: Configuration = {
+		migrate: {
+			tasks: {},
+		},
+	};
+
+	public constructor(baseDir: string, cliVersion: string, projectVersion: string, config: Configuration) {
+		this.setBaseDir(baseDir);
+		this.setCliVersion(cliVersion);
+		this.setProjectVersion(projectVersion);
+		this.setConfig(config);
+	}
+
+	private setBaseDir(baseDir: string): void {
+		if (!fs.existsSync(path.resolve(process.cwd(), baseDir))) {
+			throw logAndCreateError(`Base directory "${baseDir}" does not exist`);
+		}
+		this.baseDir = baseDir;
+	}
+
+	private setCliVersion(version: string): void {
+		if (semver.valid(version) === null) {
+			throw logAndCreateError(`Invalid CLI version: ${version}`);
+		}
+		this.cliVersion = version;
+	}
+
+	public setProjectVersion(version: string): void {
+		if (semver.valid(version) === null) {
+			throw logAndCreateError(`Invalid project version: ${version}`);
+		}
+		if (this.projectVersion !== version) {
+			this.projectVersion = version;
+		}
+	}
+
+	private setConfig(config: Configuration): void {
+		if (config.migrate?.tasks) {
+			this.config.migrate!.tasks = {
+				...this.config.migrate!.tasks,
+				...config.migrate?.tasks,
+			};
+		}
+	}
+
+	public registerTasks(tasks: AbstractTask[]): void {
+		tasks.forEach((task) => {
+			if (
+				semver.gtr(this.projectVersion, task.getVersionRange(), {
+					includePrerelease: true,
+				})
+			) {
+				console.log(
+					`Task "${task.getTitle()}" will be excluded. The current version (${
+						this.projectVersion
+					}) is greater than the task version range (${task.getVersionRange()}).`,
+				);
+				this.config.migrate!.tasks[task.getIdentifier()] = false;
+			} else {
+				this.tasks.set(task.getIdentifier(), task);
+			}
+		});
+	}
+
+	private registerTask(task: AbstractTask): void {
+		this.registerTasks([task]);
+	}
+
+	private runTask(task: AbstractTask): void {
+		if (this.config.migrate?.tasks[task.getIdentifier()] === false) {
+			task.setStatus('skipped');
+		} else {
+			this.config.migrate!.tasks[task.getIdentifier()] = true;
+			if (
+				task.getStatus() === 'pending' &&
+				semver.satisfies(this.projectVersion, task.getVersionRange(), {
+					includePrerelease: true,
+				})
+			) {
+				// task.setStatus('running'); only of the task is async
+				if (!this.tasks.has(task.getIdentifier())) {
+					this.registerTask(task);
+				}
+				task.run(this.baseDir);
+				task.setStatus('done');
+			}
+		}
+	}
+
+	private dependentTaskRun(task: AbstractTask, dependentTasks: AbstractTask[]) {
+		dependentTasks.forEach((dependentTask) => {
+			this.dependentTaskRun(dependentTask, dependentTask.getDependentTasks());
+		});
+		if (dependentTasks.every((dependentTask) => dependentTask.getStatus() === 'done')) {
+			this.runTask(task);
+		}
+	}
+
+	public run(): void {
+		this.tasks.forEach((task) => {
+			this.dependentTaskRun(task, task.getDependentTasks());
+		});
+	}
+
+	public getPendingMinVersion(): string {
+		let version: string = this.cliVersion;
+		this.tasks.forEach((task) => {
+			if (task.getStatus() === 'pending') {
+				const minVersion = semver.minVersion(task.getVersionRange())?.raw ?? this.cliVersion;
+				if (semver.gt(version, minVersion)) {
+					version = minVersion;
+				}
+			}
+		});
+		return version;
+	}
+
+	public getStatus(outline = false): {
+		done: number;
+		pending: number;
+		total: number;
+		nextVersion: string | null;
+		config: Configuration;
+	} {
+		let done = 0;
+		let pending = 0;
+		this.tasks.forEach((task) => {
+			switch (task.getStatus()) {
+				case 'done':
+					done++;
+					break;
+				case 'pending':
+					pending++;
+					break;
+			}
+			if (outline) {
+				const status = task.getStatus();
+				console.log(`- ${task.getTitle()}:`, status === 'done' ? chalk.green(status) : chalk.yellow(status));
+			}
+		});
+		return {
+			done: done,
+			pending: pending,
+			total: this.tasks.size,
+			nextVersion: this.getPendingMinVersion(),
+			config: this.config,
+		};
+	}
+}