@cratis/components.migrator 0.0.0 → 4.1.0

package/lib/changeHandlerTransform.js

@@ -0,0 +1,380 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import ts from 'typescript';
+import { packageName as defaultPackageName } from './namespaceMap.js';
+
+const TODO = 'TODO(cratis-codemod)';
+const affectedComponents = {
+    CommandForm: {
+        InputTextField: new Set(['target.value', 'currentTarget.value']),
+        PasswordField: new Set(['target.value', 'currentTarget.value']),
+        TextAreaField: new Set(['target.value', 'currentTarget.value']),
+        ColorPickerField: new Set(['target.value', 'currentTarget.value']),
+        CheckboxField: new Set(['target.checked', 'currentTarget.checked']),
+        ToggleSwitchField: new Set(['target.checked', 'currentTarget.checked']),
+        NumberField: new Set(['target.valueAsNumber', 'currentTarget.valueAsNumber']),
+        SliderField: new Set(['target.valueAsNumber', 'currentTarget.valueAsNumber']),
+        DropdownField: new Set(['value']),
+        MultiSelectField: new Set(['value']),
+    },
+    Dropdown: {
+        Dropdown: new Set(['value']),
+    },
+};
+
+/**
+ * Rewrites structurally-proven legacy event-wrapper JSX callbacks to semantic values.
+ *
+ * @param {string} fileName
+ * @param {string} text
+ * @param {{ packageName?: string }} [options]
+ */
+export function transformChangeHandlers(fileName, text, options = {}) {
+    const packageName = options.packageName ?? defaultPackageName;
+    const sourceFile = ts.createSourceFile(
+        fileName,
+        text,
+        ts.ScriptTarget.Latest,
+        true,
+        scriptKindFor(fileName),
+    );
+    const named = new Map();
+    const namespaces = new Map();
+    const diagnostics = [];
+    const edits = [];
+
+    for (const statement of sourceFile.statements) {
+        if (
+            !ts.isImportDeclaration(statement) ||
+            !ts.isStringLiteral(statement.moduleSpecifier) ||
+            !statement.importClause ||
+            statement.importClause.isTypeOnly
+        )
+            continue;
+        const group = groupForSpecifier(statement.moduleSpecifier.text, packageName);
+        if (!group) continue;
+        const bindings = statement.importClause.namedBindings;
+        if (bindings && ts.isNamespaceImport(bindings)) {
+            namespaces.set(bindings.name.text, group);
+        } else if (bindings && ts.isNamedImports(bindings)) {
+            for (const element of bindings.elements) {
+                const imported = (element.propertyName ?? element.name).text;
+                if (
+                    !ts.isTypeOnlyImportOrExportDeclaration(element) &&
+                    affectedComponents[group][imported]
+                ) {
+                    named.set(element.name.text, { group, component: imported });
+                }
+            }
+        }
+    }
+
+    const report = (node, component, reason) => {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+            node.getStart(sourceFile),
+        );
+        diagnostics.push({
+            file: fileName,
+            line: line + 1,
+            column: character + 1,
+            message: `${component} change-handler migration requires manual review: ${reason}. The callback was left unchanged.`,
+        });
+    };
+
+    const visit = (node) => {
+        if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+            const target = resolveTarget(node.tagName, named, namespaces);
+            if (target) migrateCallbacks(node, target);
+        }
+        ts.forEachChild(node, visit);
+    };
+
+    const migrateCallbacks = (opening, target) => {
+        const allowed = affectedComponents[target.group][target.component];
+        for (const attribute of opening.attributes.properties) {
+            if (!ts.isJsxAttribute(attribute)) continue;
+            const propName = attribute.name.getText(sourceFile);
+            if (propName !== 'onChange' && propName !== 'onValueChange') continue;
+            if (
+                !attribute.initializer ||
+                !ts.isJsxExpression(attribute.initializer) ||
+                !attribute.initializer.expression
+            )
+                continue;
+
+            const callback = unwrap(attribute.initializer.expression);
+            if (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback))
+                continue;
+            const result = analyzeCallback(callback, allowed);
+            if (result.kind === 'already-semantic' || result.kind === 'irrelevant')
+                continue;
+            if (result.kind === 'unsupported') {
+                report(attribute, target.component, result.reason);
+                annotate(attribute);
+                continue;
+            }
+
+            edits.push({
+                start: result.parameter.getStart(sourceFile),
+                end: result.parameter.getEnd(),
+                replacement: result.name,
+            });
+            edits.push({
+                start: result.argument.getStart(sourceFile),
+                end: result.argument.getEnd(),
+                replacement: result.name,
+            });
+        }
+    };
+
+    const annotate = (attribute) => {
+        if (attribute.getText(sourceFile).includes(TODO)) return;
+        const expression = attribute.initializer?.expression;
+        if (!expression) return;
+        edits.push({
+            start: expression.getStart(sourceFile),
+            end: expression.getStart(sourceFile),
+            replacement: `/* ${TODO}: review ambiguous Components change handler. */ `,
+        });
+    };
+
+    visit(sourceFile);
+    return applyEdits(text, edits, diagnostics);
+}
+
+function groupForSpecifier(specifier, packageName) {
+    if (
+        specifier === `${packageName}/CommandForm` ||
+        specifier === `${packageName}/CommandForm/fields`
+    )
+        return 'CommandForm';
+    if (specifier === `${packageName}/Dropdown`) return 'Dropdown';
+    return undefined;
+}
+
+function resolveTarget(tag, named, namespaces) {
+    if (ts.isIdentifier(tag)) return named.get(tag.text);
+    if (!ts.isPropertyAccessExpression(tag) || !ts.isIdentifier(tag.expression))
+        return undefined;
+    const group = namespaces.get(tag.expression.text);
+    if (!group || !affectedComponents[group][tag.name.text]) return undefined;
+    return { group, component: tag.name.text };
+}
+
+function analyzeCallback(callback, allowed) {
+    if (callback.parameters.length !== 1) {
+        return hasLegacyLookingAccess(callback, callback.parameters[0])
+            ? {
+                  kind: 'unsupported',
+                  reason: 'the callback has multiple parameters or an unsupported parameter shape',
+              }
+            : { kind: 'irrelevant' };
+    }
+
+    const parameter = callback.parameters[0];
+    if (parameter.dotDotDotToken || parameter.initializer) {
+        return {
+            kind: 'unsupported',
+            reason: 'rest/default callback parameters are not statically safe',
+        };
+    }
+
+    const binding = bindingAccess(parameter.name);
+    if (!binding) {
+        return {
+            kind: 'unsupported',
+            reason: 'the destructured callback parameter is not a single event value field',
+        };
+    }
+
+    const call = singleCall(callback.body);
+    if (!call || call.arguments.length !== 1) {
+        return callbackUsesBinding(callback, binding)
+            ? {
+                  kind: 'unsupported',
+                  reason: 'the callback is not a single one-argument forwarding call',
+              }
+            : { kind: 'irrelevant' };
+    }
+
+    const argument = unwrap(call.arguments[0]);
+    const access = accessFromArgument(argument, binding);
+    const references = bindingReferences(callback, binding);
+
+    if (access && allowed.has(access) && references === 1) {
+        const name = containsIdentifier(call.expression, 'value') ? 'nextValue' : 'value';
+        return { kind: 'rewrite', parameter, argument: call.arguments[0], name };
+    }
+
+    if (access || references > 0 || hasLegacyLookingAccess(callback, parameter)) {
+        if (
+            binding.kind === 'identifier' &&
+            references === 1 &&
+            ts.isIdentifier(argument) &&
+            argument.text === binding.localName
+        ) {
+            return /^(e|event|evt|changeEvent)$/iu.test(binding.localName)
+                ? {
+                      kind: 'unsupported',
+                      reason: 'the callback forwards an event-looking parameter without proving its semantic value',
+                  }
+                : { kind: 'already-semantic' };
+        }
+        return {
+            kind: 'unsupported',
+            reason:
+                access && !allowed.has(access)
+                    ? `it reads '${access}', which is not the legacy payload shape for this component`
+                    : 'the event parameter is used more than once or the callback depends on native-event details',
+        };
+    }
+
+    return { kind: 'irrelevant' };
+}
+
+function bindingAccess(name) {
+    if (ts.isIdentifier(name)) return { kind: 'identifier', localName: name.text };
+    if (!ts.isObjectBindingPattern(name) || name.elements.length !== 1) return undefined;
+    const element = name.elements[0];
+    if (element.dotDotDotToken || element.initializer) return undefined;
+    const first = (element.propertyName ?? element.name).getText();
+    if (
+        ts.isIdentifier(element.name) &&
+        (first === 'value' || first === 'checked' || first === 'valueAsNumber')
+    ) {
+        return { kind: 'destructured', access: first, localName: element.name.text };
+    }
+    if (
+        (first === 'target' || first === 'currentTarget') &&
+        ts.isObjectBindingPattern(element.name) &&
+        element.name.elements.length === 1
+    ) {
+        const nested = element.name.elements[0];
+        if (nested.dotDotDotToken || nested.initializer || !ts.isIdentifier(nested.name))
+            return undefined;
+        const property = (nested.propertyName ?? nested.name).getText();
+        if (
+            property === 'value' ||
+            property === 'checked' ||
+            property === 'valueAsNumber'
+        ) {
+            return {
+                kind: 'destructured',
+                access: `${first}.${property}`,
+                localName: nested.name.text,
+            };
+        }
+    }
+    return undefined;
+}
+
+function singleCall(body) {
+    if (!ts.isBlock(body)) {
+        const expression = unwrap(body);
+        return ts.isCallExpression(expression) ? expression : undefined;
+    }
+    if (body.statements.length !== 1) return undefined;
+    const statement = body.statements[0];
+    if (ts.isExpressionStatement(statement)) {
+        const expression = unwrap(statement.expression);
+        return ts.isCallExpression(expression) ? expression : undefined;
+    }
+    if (ts.isReturnStatement(statement) && statement.expression) {
+        const expression = unwrap(statement.expression);
+        return ts.isCallExpression(expression) ? expression : undefined;
+    }
+    return undefined;
+}
+
+function accessFromArgument(argument, binding) {
+    if (binding.kind === 'destructured') {
+        return ts.isIdentifier(argument) && argument.text === binding.localName
+            ? binding.access
+            : undefined;
+    }
+    const parts = [];
+    let current = argument;
+    while (ts.isPropertyAccessExpression(current)) {
+        parts.unshift(current.name.text);
+        current = unwrap(current.expression);
+    }
+    return ts.isIdentifier(current) && current.text === binding.localName
+        ? parts.join('.')
+        : undefined;
+}
+
+function bindingReferences(callback, binding) {
+    let count = 0;
+    const visit = (node) => {
+        if (node === callback.parameters[0]) return;
+        if (ts.isIdentifier(node) && node.text === binding.localName) count += 1;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(callback.body, visit);
+    return count;
+}
+
+function callbackUsesBinding(callback, binding) {
+    return bindingReferences(callback, binding) > 0;
+}
+
+function hasLegacyLookingAccess(callback, parameter) {
+    if (!parameter || !ts.isIdentifier(parameter.name)) return false;
+    const root = parameter.name.text;
+    let found = false;
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node)) {
+            let current = node;
+            while (ts.isPropertyAccessExpression(current))
+                current = unwrap(current.expression);
+            if (ts.isIdentifier(current) && current.text === root) found = true;
+        }
+        if (!found) ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(callback.body, visit);
+    return found;
+}
+
+function containsIdentifier(node, name) {
+    let found = false;
+    const visit = (child) => {
+        if (ts.isIdentifier(child) && child.text === name) found = true;
+        if (!found) ts.forEachChild(child, visit);
+    };
+    visit(node);
+    return found;
+}
+
+function unwrap(node) {
+    while (
+        ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isTypeAssertionExpression(node)
+    )
+        node = node.expression;
+    return node;
+}
+
+function applyEdits(text, edits, diagnostics) {
+    if (edits.length === 0) return { text, changed: false, diagnostics };
+    edits.sort((a, b) => a.start - b.start || a.end - b.end);
+    let output = text;
+    for (let index = edits.length - 1; index >= 0; index--) {
+        const edit = edits[index];
+        output = output.slice(0, edit.start) + edit.replacement + output.slice(edit.end);
+    }
+    return { text: output, changed: output !== text, diagnostics };
+}
+
+function scriptKindFor(fileName) {
+    if (fileName.endsWith('.tsx')) return ts.ScriptKind.TSX;
+    if (fileName.endsWith('.jsx')) return ts.ScriptKind.JSX;
+    if (
+        fileName.endsWith('.js') ||
+        fileName.endsWith('.mjs') ||
+        fileName.endsWith('.cjs')
+    )
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}

package/lib/compatibility.js

@@ -0,0 +1,164 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+
+const packageDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const bundledManifestPath = path.join(packageDirectory, 'compat-manifest.json');
+const migratorPackagePath = path.join(packageDirectory, 'package.json');
+
+/** Validates the bundled release contract and the installed Components migration boundary. */
+export function preflightCompatibility({
+    cwd = process.cwd(),
+    packageName = '@cratis/components',
+} = {}) {
+    const manifest = readJson(bundledManifestPath, 'bundled compatibility manifest');
+    const migratorPackage = readJson(migratorPackagePath, 'migrator package manifest');
+    validateBundledManifest(manifest, migratorPackage.version);
+
+    const installedPackagePath = resolvePackageManifest(packageName, cwd);
+    const installedPackage = readJson(
+        installedPackagePath,
+        `installed ${packageName} package manifest`,
+    );
+    if (installedPackage.name !== packageName) {
+        throw new Error(
+            `Resolved ${packageName} package manifest declares unexpected name '${installedPackage.name ?? '<missing>'}'.`,
+        );
+    }
+    if (semver.valid(installedPackage.version) !== installedPackage.version) {
+        throw new Error(
+            `Installed ${packageName} has invalid version '${installedPackage.version ?? '<missing>'}'.`,
+        );
+    }
+
+    const supportedWindow = Object.values(manifest.supportWindows).find(
+        (window) =>
+            ['source', 'target'].includes(window.migrationRole) &&
+            semver.satisfies(installedPackage.version, window.components),
+    );
+    if (!supportedWindow) {
+        const ranges = Object.values(manifest.supportWindows)
+            .filter((window) => ['source', 'target'].includes(window.migrationRole))
+            .map((window) => window.components)
+            .join(' or ');
+        throw new Error(
+            `Installed ${packageName}@${installedPackage.version} is unsupported by this codemod. ` +
+                `Allowed migration Components ranges: ${ranges}.`,
+        );
+    }
+    const windowMigratorRange =
+        typeof supportedWindow.tooling === 'string'
+            ? supportedWindow.tooling
+            : supportedWindow.tooling?.migrator;
+    if (
+        !semver.validRange(windowMigratorRange) ||
+        !semver.satisfies(migratorPackage.version, windowMigratorRange)
+    ) {
+        throw new Error(
+            `Migrator ${migratorPackage.version} is incompatible with the ${supportedWindow.migrationRole} support window tooling range '${windowMigratorRange ?? '<missing>'}'.`,
+        );
+    }
+
+    return {
+        manifest,
+        migratorVersion: migratorPackage.version,
+        componentsVersion: installedPackage.version,
+        migrationRole: supportedWindow.migrationRole,
+    };
+}
+
+/** Validates data that must remain true for the packed migrator to run safely. */
+export function validateBundledManifest(manifest, migratorVersion) {
+    if (!manifest || manifest.schemaVersion !== 2) {
+        throw new Error('Bundled compatibility manifest has an unsupported schema.');
+    }
+    if (
+        !['source-candidate', 'publication-authorized'].includes(manifest.releaseStatus)
+    ) {
+        throw new Error('Bundled compatibility manifest has an invalid releaseStatus.');
+    }
+    const migratorRange = manifest.toolingCompatibility?.migrator;
+    if (!semver.validRange(migratorRange)) {
+        throw new Error('Bundled compatibility manifest has an invalid migrator range.');
+    }
+    if (semver.valid(migratorVersion) !== migratorVersion) {
+        throw new Error(`Migrator package has invalid version '${migratorVersion}'.`);
+    }
+    if (!semver.satisfies(migratorVersion, migratorRange)) {
+        throw new Error(
+            `Migrator package version ${migratorVersion} is outside bundled range '${migratorRange}'.`,
+        );
+    }
+
+    const packageEntry = manifest.packages?.find(
+        ({ name }) => name === '@cratis/components.migrator',
+    );
+    if (
+        packageEntry?.version !== migratorVersion ||
+        packageEntry?.independentRelease !== false ||
+        !semver.satisfies(migratorVersion, packageEntry?.releaseMajorRange ?? '')
+    ) {
+        throw new Error(
+            'Bundled compatibility manifest has stale migrator package metadata.',
+        );
+    }
+
+    const windows = Object.values(manifest.supportWindows ?? {});
+    const sourceWindows = windows.filter(
+        ({ migrationRole }) => migrationRole === 'source',
+    );
+    const targetWindows = windows.filter(
+        ({ migrationRole }) => migrationRole === 'target',
+    );
+    if (
+        windows.length !== 2 ||
+        sourceWindows.length !== 1 ||
+        targetWindows.length !== 1 ||
+        sourceWindows[0].components !== '>=3 <4' ||
+        sourceWindows[0].migrationTarget !== '>=4 <5' ||
+        targetWindows[0].components !== '>=4 <5' ||
+        manifest.toolingCompatibility?.componentsCore !== '>=4 <5' ||
+        windows.some((window) => {
+            const toolingRange =
+                typeof window.tooling === 'string'
+                    ? window.tooling
+                    : window.tooling?.migrator;
+            return (
+                !semver.validRange(window.components) || !semver.validRange(toolingRange)
+            );
+        })
+    ) {
+        throw new Error(
+            'Bundled compatibility manifest has invalid migration support windows.',
+        );
+    }
+}
+
+function resolvePackageManifest(packageName, cwd) {
+    try {
+        const requireFromCwd = createRequire(
+            path.join(path.resolve(cwd), 'package.json'),
+        );
+        return requireFromCwd.resolve(`${packageName}/package.json`);
+    } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(
+            `Could not resolve installed ${packageName} from '${path.resolve(cwd)}'. ` +
+                `Install a supported Components 3 or Components 4 package before running the codemod. ${detail}`,
+        );
+    }
+}
+
+function readJson(filePath, description) {
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read ${description}: ${detail}`);
+    }
+}

package/lib/namespaceMap.js

@@ -0,0 +1,87 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Single source of truth for the root-namespace-removal migration: every component
+ * namespace removed from the Components 3 package root, and the small setup surface
+ * that remains supported at the Components 4 root.
+ *
+ * Mirrors `Source/index.ts` and the `exports` map in `Source/package.json`. When a
+ * namespace subpath is added, renamed, or removed there, update `namespaceSubpaths`
+ * here (and the matching copy in `ESLint/lib/rootNamespaceMap.js`) in the same change.
+ * Neither file imports the other: this package and `@cratis/eslint-plugin-components`
+ * ship and publish independently, so the map is intentionally duplicated rather than
+ * shared across a workspace boundary.
+ */
+
+/** The package this migration applies to by default. */
+export const packageName = '@cratis/components';
+
+/**
+ * Every retained namespace removed from the Components 3 root, mapped to the Components 4
+ * subpath it becomes: `import { Canvas } from '@cratis/components'` migrates to
+ * `import * as Canvas from '@cratis/components/Canvas'`. `Types` is the one case where
+ * the namespace name and its subpath differ in casing (`./types`, lowercase).
+ */
+export const namespaceSubpaths = {
+    Canvas: 'Canvas',
+    Chat: 'Chat',
+    CommandDialog: 'CommandDialog',
+    // The former root CommandStepper namespace aliased the entire CommandDialog module.
+    // Preserve that module identity; the narrower ./CommandStepper subpath does not.
+    CommandStepper: 'CommandDialog',
+    CommandForm: 'CommandForm',
+    Common: 'Common',
+    DataPage: 'DataPage',
+    DataTables: 'DataTables',
+    Dialogs: 'Dialogs',
+    Display: 'Display',
+    Dropdown: 'Dropdown',
+    Filter: 'Filter',
+    Notifications: 'Notifications',
+    ObjectContentEditor: 'ObjectContentEditor',
+    ObjectNavigationalBar: 'ObjectNavigationalBar',
+    PivotViewer: 'PivotViewer',
+    SchemaEditor: 'SchemaEditor',
+    TimeMachine: 'TimeMachine',
+    Toolbar: 'Toolbar',
+    Types: 'types',
+};
+
+/**
+ * Components 3 root exports that have no Components 4 root or subpath equivalent.
+ * These are known migration boundaries rather than unknown symbols: transforms must
+ * refuse them with actionable renderer-removal guidance instead of suggesting that the
+ * namespace map is incomplete.
+ */
+export const removedRootSymbols = new Set([
+    'Compatibility',
+    'assertPrimeReact11PassThroughCompatibility',
+    'components3PrimeReact11PassThroughContract',
+    'primeReact11PassThroughSentinelAttribute',
+    'primeReact11PassThroughSentinelPreset',
+    'PrimeReact11PassThroughComponent',
+]);
+
+/**
+ * The primary setup surface Source/index.ts re-exports directly from the root so a
+ * consumer that only wants provider setup does not need to know about the `Common`
+ * subpath. These names are never rewritten to a namespace import.
+ */
+export const approvedRootSymbols = new Set([
+    'CratisComponentsProvider',
+    'useCratisComponentsConfig',
+    'cratisDefaults',
+    'mergeCratisComponentsConfig',
+    'CratisComponentsConfig',
+    'CratisComponentsProviderProps',
+    'CratisComponentsMessages',
+    'CratisPaginatorMessages',
+    'CratisDatePickerMessages',
+    'CratisDropdownMessages',
+    'CratisDialogMessages',
+    'CratisStepperMessages',
+    'CratisNotificationsMessages',
+    'CratisDataTableMessages',
+    'CratisColumnFilterMessages',
+]);