@cratis/components.migrator 0.0.0 → 4.1.0

package/lib/runTransformCli.js

@@ -0,0 +1,137 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync, writeFileSync, statSync, readdirSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { packageName as defaultPackageName } from './namespaceMap.js';
+import { preflightCompatibility } from './compatibility.js';
+
+const EXTENSIONS = new Set([
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+]);
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', '.yarn']);
+
+/** Runs one independently invocable Components codemod CLI. */
+export function runTransformCli(argv, { command, description, transform }) {
+    const args = [...argv];
+    let check = false;
+    let packageName = defaultPackageName;
+    const paths = [];
+
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (arg === '--check') check = true;
+        else if (arg === '--package') {
+            const configuredPackage = args.shift();
+            if (!configuredPackage) {
+                console.error('--package requires a package name.');
+                return 1;
+            }
+            packageName = configuredPackage;
+        } else if (arg === '--help' || arg === '-h') {
+            printUsage(command, description);
+            return 0;
+        } else if (arg.startsWith('-')) {
+            console.error(`Unknown option: ${arg}`);
+            return 1;
+        } else paths.push(arg);
+    }
+
+    if (paths.length === 0) {
+        printUsage(command, description);
+        return 1;
+    }
+
+    try {
+        preflightCompatibility({ packageName });
+    } catch (error) {
+        console.error(
+            `Compatibility preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return 1;
+    }
+
+    let files;
+    try {
+        files = paths.flatMap(collectFiles);
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+
+    let changedCount = 0;
+    let diagnosticCount = 0;
+    let errorCount = 0;
+    for (const file of files) {
+        try {
+            const original = readFileSync(file, 'utf8');
+            const result = transform(file, original, { packageName });
+            for (const diagnostic of result.diagnostics) {
+                diagnosticCount += 1;
+                console.warn(
+                    `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}: ${diagnostic.message}`,
+                );
+            }
+            if (result.changed) {
+                changedCount += 1;
+                if (check) console.log(`would rewrite ${file}`);
+                else {
+                    writeFileSync(file, result.text, 'utf8');
+                    console.log(`rewrote ${file}`);
+                }
+            }
+        } catch (error) {
+            errorCount += 1;
+            console.error(
+                `${file}: failed to process: ${error instanceof Error ? error.message : String(error)}`,
+            );
+        }
+    }
+
+    console.log(
+        `\n${files.length} file(s) scanned, ${changedCount} ${check ? 'would change' : 'changed'}, ${diagnosticCount} unsupported or ambiguous case(s) reported, ${errorCount} processing error(s).`,
+    );
+    if (diagnosticCount > 0 || errorCount > 0 || (check && changedCount > 0)) return 1;
+    return 0;
+}
+
+function printUsage(command, description) {
+    console.log(
+        [
+            `Usage: ${command} [--check] [--package <name>] <path...>`,
+            '',
+            description,
+            '',
+            'Options:',
+            '  --check           Report what would change without writing files; exits 1 if',
+            '                    anything would change or manual review is required.',
+            '  --package <name>  Components package name (default: @cratis/components).',
+            '',
+            '<path...> may be files or directories; directories are walked recursively for',
+            '.js/.jsx/.mjs/.cjs/.ts/.tsx/.mts/.cts files, skipping node_modules,',
+            'dist, .git, and .yarn.',
+        ].join('\n'),
+    );
+}
+
+function collectFiles(inputPath) {
+    const stats = statSync(inputPath);
+    if (stats.isFile()) return EXTENSIONS.has(extname(inputPath)) ? [inputPath] : [];
+    if (!stats.isDirectory()) return [];
+    const files = [];
+    for (const entry of readdirSync(inputPath, { withFileTypes: true })) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const entryPath = join(inputPath, entry.name);
+        if (entry.isDirectory()) files.push(...collectFiles(entryPath));
+        else if (entry.isFile() && EXTENSIONS.has(extname(entry.name)))
+            files.push(entryPath);
+    }
+    return files;
+}

package/lib/transform.js

@@ -0,0 +1,355 @@
+// 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,
+    namespaceSubpaths,
+    approvedRootSymbols,
+    removedRootSymbols,
+} from './namespaceMap.js';
+
+/**
+ * Rewrites static imports of the `@cratis/components` root barrel into subpath
+ * namespace imports, using the TypeScript compiler API for exact, position-based text
+ * edits rather than a full reprint — every untouched line of the file, including
+ * comments and formatting, is left byte-identical.
+ *
+ * What it does:
+ * - `import { Canvas } from '@cratis/components'` becomes
+ *   `import * as Canvas from '@cratis/components/Canvas'`.
+ * - `import type { Canvas } from '@cratis/components'` becomes
+ *   `import type * as Canvas from '@cratis/components/Canvas'`; a per-specifier
+ *   `type` modifier (`import { type Canvas } from ...`) is honored the same way.
+ * - Aliases are preserved: `import { Canvas as C } from '@cratis/components'` becomes
+ *   `import * as C from '@cratis/components/Canvas'`.
+ * - A mixed import naming both an approved setup symbol and a namespace is split: the
+ *   setup symbol stays imported from the root, each namespace becomes its own subpath
+ *   import.
+ * - An import naming several namespaces produces one subpath import per namespace, in
+ *   their original left-to-right order.
+ * - A named re-export follows the same rules: `export { Canvas } from '@cratis/components'`
+ *   becomes `export * as Canvas from '@cratis/components/Canvas'`, with the same alias,
+ *   type-only, mixed-setup-symbol, and multiple-namespace handling as the import case.
+ * - Applying the codemod again is a no-op: it only ever matches an import or named
+ *   re-export whose module specifier is exactly the configured package name, so an
+ *   already-migrated subpath import or re-export is never revisited.
+ *
+ * What it deliberately refuses to guess, reporting a diagnostic instead of editing:
+ * - A namespace import of the whole package (`import * as Components from '...'`) —
+ *   which subpath each later `Components.X` access belongs to cannot be determined
+ *   from the import alone.
+ * - A default import (`import Components from '...'`) — the package has no default
+ *   export.
+ * - A side-effect-only import (`import '...'`) — there is no binding to infer a
+ *   subpath from.
+ * - A named import or named re-export of a symbol that is neither an approved setup
+ *   symbol nor a known namespace — the whole statement is left untouched so a
+ *   partial, silently incomplete migration is never produced.
+ * - A known removed Components 3 renderer-compatibility export — it has no Components 4
+ *   subpath, so the statement is left untouched with typed-parts guidance.
+ * - A dynamic `import('...')` or CommonJS `require('...')` call anywhere in the file.
+ * - A wildcard re-export of the whole package (`export * from '@cratis/components'`)
+ *   or a namespace re-export of the whole package (`export * as X from
+ *   '@cratis/components'`) — the same ambiguity as a whole-package namespace import:
+ *   which subpath each later access belongs to cannot be determined from the
+ *   re-export alone.
+ *
+ * @param {string} fileName - Used only to select the TypeScript/TSX/JS/JSX grammar.
+ * @param {string} text - The source file's current contents.
+ * @param {{ packageName?: string }} [options]
+ * @returns {{ text: string, changed: boolean, diagnostics: Array<{ file: string, line: number, column: number, message: string }> }}
+ */
+export function transformSource(fileName, text, options = {}) {
+    const packageName = options.packageName ?? defaultPackageName;
+    const sourceFile = ts.createSourceFile(
+        fileName,
+        text,
+        ts.ScriptTarget.Latest,
+        true,
+        scriptKindFor(fileName),
+    );
+
+    const diagnostics = [];
+    const edits = [];
+
+    const isRootSpecifier = (moduleSpecifier) =>
+        !!moduleSpecifier &&
+        ts.isStringLiteral(moduleSpecifier) &&
+        moduleSpecifier.text === packageName;
+
+    const report = (node, message) => {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+            node.getStart(sourceFile),
+        );
+        diagnostics.push({
+            file: fileName,
+            line: line + 1,
+            column: character + 1,
+            message,
+        });
+    };
+
+    const handleImport = (node) => {
+        if (!isRootSpecifier(node.moduleSpecifier)) return;
+
+        const importClause = node.importClause;
+        if (!importClause) {
+            report(
+                node,
+                `Side-effect-only import of '${packageName}' cannot be auto-migrated: there is no named binding to infer a subpath from. Import the specific subpath directly, or remove the import if it has no effect.`,
+            );
+            return;
+        }
+        if (importClause.name) {
+            report(
+                node,
+                `Default import of '${packageName}' cannot be auto-migrated: the package has no default export. Replace it with the subpath import(s) it actually needs.`,
+            );
+            return;
+        }
+
+        const bindings = importClause.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings)) {
+            report(
+                node,
+                `Namespace import of '${packageName}' cannot be auto-migrated: which subpath each later member access belongs to cannot be inferred from the import alone. Replace it with the specific namespace subpath import(s) it needs.`,
+            );
+            return;
+        }
+
+        const declTypeOnly = importClause.isTypeOnly;
+        const kept = [];
+        const namespaced = [];
+        let hasUnknown = false;
+
+        for (const element of bindings.elements) {
+            const importedName = (element.propertyName ?? element.name).text;
+            const localName = element.name.text;
+
+            if (approvedRootSymbols.has(importedName)) {
+                kept.push({
+                    name: importedName,
+                    localName,
+                    elementTypeOnly: element.isTypeOnly,
+                });
+                continue;
+            }
+            if (Object.hasOwn(namespaceSubpaths, importedName)) {
+                namespaced.push({
+                    localName,
+                    subpath: namespaceSubpaths[importedName],
+                    typeOnly: declTypeOnly || element.isTypeOnly,
+                });
+                continue;
+            }
+            if (removedRootSymbols.has(importedName)) {
+                hasUnknown = true;
+                report(
+                    element,
+                    `'${importedName}' was a Components 3 PrimeReact compatibility export and has no Components 4 subpath. Leaving this import untouched — migrate renderer slots to typed Cratis parts and remove the compatibility export manually.`,
+                );
+                continue;
+            }
+
+            hasUnknown = true;
+            report(
+                element,
+                `'${importedName}' is not a recognized '${packageName}' root export (neither an approved setup symbol nor a known namespace). Leaving this import untouched — add '${importedName}' to the migration map, or migrate it by hand.`,
+            );
+        }
+
+        // Never guess: an unrecognized specifier means the whole statement is left as-is,
+        // even for the specifiers this codemod does recognize.
+        if (hasUnknown) return;
+        // Nothing to migrate — the import already only names approved root symbols.
+        if (namespaced.length === 0) return;
+
+        const replacement = buildSubpathReplacementText({
+            keyword: 'import',
+            packageName,
+            declTypeOnly,
+            kept,
+            namespaced,
+        });
+        edits.push({ start: node.getStart(sourceFile), end: node.getEnd(), replacement });
+    };
+
+    const handleExport = (node) => {
+        if (!isRootSpecifier(node.moduleSpecifier)) return;
+
+        if (!node.exportClause || !ts.isNamedExports(node.exportClause)) {
+            // A bare `export * from '@cratis/components'` or a namespace re-export
+            // (`export * as X from '@cratis/components'`) is exactly as ambiguous as a
+            // whole-package namespace import: there is no way to know, from the
+            // re-export alone, which subpath a later consumer's member access needs.
+            report(
+                node,
+                `A wildcard 're-export … from ${JSON.stringify(packageName)}' cannot be auto-migrated: which subpath each later member access belongs to cannot be inferred from the re-export alone. Replace it with explicit subpath re-export(s).`,
+            );
+            return;
+        }
+
+        const declTypeOnly = node.isTypeOnly;
+        const kept = [];
+        const namespaced = [];
+        let hasUnknown = false;
+
+        for (const element of node.exportClause.elements) {
+            const exportedName = (element.propertyName ?? element.name).text;
+            const localName = element.name.text;
+
+            if (approvedRootSymbols.has(exportedName)) {
+                kept.push({
+                    name: exportedName,
+                    localName,
+                    elementTypeOnly: element.isTypeOnly,
+                });
+                continue;
+            }
+            if (Object.hasOwn(namespaceSubpaths, exportedName)) {
+                namespaced.push({
+                    localName,
+                    subpath: namespaceSubpaths[exportedName],
+                    typeOnly: declTypeOnly || element.isTypeOnly,
+                });
+                continue;
+            }
+            if (removedRootSymbols.has(exportedName)) {
+                hasUnknown = true;
+                report(
+                    element,
+                    `'${exportedName}' was a Components 3 PrimeReact compatibility export and has no Components 4 subpath. Leaving this re-export untouched — migrate renderer slots to typed Cratis parts and remove the compatibility export manually.`,
+                );
+                continue;
+            }
+
+            hasUnknown = true;
+            report(
+                element,
+                `'${exportedName}' is not a recognized '${packageName}' root export (neither an approved setup symbol nor a known namespace). Leaving this re-export untouched — add '${exportedName}' to the migration map, or migrate it by hand.`,
+            );
+        }
+
+        // Never guess: an unrecognized specifier means the whole statement is left as-is,
+        // even for the specifiers this codemod does recognize.
+        if (hasUnknown) return;
+        // Nothing to migrate — the re-export already only names approved root symbols.
+        if (namespaced.length === 0) return;
+
+        const replacement = buildSubpathReplacementText({
+            keyword: 'export',
+            packageName,
+            declTypeOnly,
+            kept,
+            namespaced,
+        });
+        edits.push({ start: node.getStart(sourceFile), end: node.getEnd(), replacement });
+    };
+
+    const handleImportEquals = (node) => {
+        if (!ts.isExternalModuleReference(node.moduleReference)) return;
+        if (!isRootSpecifier(node.moduleReference.expression)) return;
+
+        report(
+            node,
+            `Import-assignment of '${packageName}' ('import ${node.name.text} = require(...)') cannot be auto-migrated: which subpath each later member access belongs to cannot be inferred from the import alone. Replace it with the specific namespace subpath import(s) it needs.`,
+        );
+    };
+
+    const checkCallExpression = (node) => {
+        const isDynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+        const isRequire =
+            ts.isIdentifier(node.expression) && node.expression.text === 'require';
+        if (!isDynamicImport && !isRequire) return;
+
+        const [arg] = node.arguments;
+        if (arg && ts.isStringLiteral(arg) && arg.text === packageName) {
+            const form = isDynamicImport
+                ? "dynamic 'import(...)'"
+                : "CommonJS 'require(...)'";
+            report(
+                node,
+                `A ${form} of '${packageName}' cannot be auto-migrated: this codemod only rewrites static 'import' declarations. Replace it with the specific subpath import(s) it needs.`,
+            );
+        }
+    };
+
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node)) {
+            handleImport(node);
+            return;
+        }
+        if (ts.isExportDeclaration(node)) {
+            handleExport(node);
+            return;
+        }
+        if (ts.isImportEqualsDeclaration(node)) {
+            handleImportEquals(node);
+            return;
+        }
+        if (ts.isCallExpression(node)) {
+            checkCallExpression(node);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+
+    if (edits.length === 0) {
+        return { text, changed: false, diagnostics };
+    }
+
+    edits.sort((a, b) => a.start - b.start);
+    let output = text;
+    for (let i = edits.length - 1; i >= 0; i--) {
+        const { start, end, replacement } = edits[i];
+        output = output.slice(0, start) + replacement + output.slice(end);
+    }
+
+    return { text: output, changed: true, diagnostics };
+}
+
+/**
+ * Builds replacement source text for both the import and named-re-export cases, which
+ * share an identical shape: an optional statement that keeps the approved root symbols
+ * (`{ name, localName, elementTypeOnly }` entries), followed by one `* as localName from
+ * '<package>/<subpath>'` statement per namespace (`{ localName, subpath, typeOnly }`
+ * entries). `keyword` is `'import'` or `'export'`.
+ */
+function buildSubpathReplacementText({ keyword, packageName, declTypeOnly, kept, namespaced }) {
+    const lines = [];
+
+    if (kept.length > 0) {
+        const specifiers = kept
+            .map(({ name, localName, elementTypeOnly }) => {
+                const prefix = !declTypeOnly && elementTypeOnly ? 'type ' : '';
+                const alias = localName === name ? '' : ` as ${localName}`;
+                return `${prefix}${name}${alias}`;
+            })
+            .join(', ');
+        lines.push(
+            `${keyword} ${declTypeOnly ? 'type ' : ''}{ ${specifiers} } from '${packageName}';`,
+        );
+    }
+
+    for (const { localName, subpath, typeOnly } of namespaced) {
+        lines.push(
+            `${keyword} ${typeOnly ? 'type ' : ''}* as ${localName} from '${packageName}/${subpath}';`,
+        );
+    }
+
+    return lines.join('\n');
+}
+
+function scriptKindFor(fileName) {
+    if (fileName.endsWith('.tsx')) return ts.ScriptKind.TSX;
+    if (fileName.endsWith('.jsx')) return ts.ScriptKind.JSX;
+    if (fileName.endsWith('.mts') || fileName.endsWith('.cts')) return ts.ScriptKind.TS;
+    if (
+        fileName.endsWith('.js') ||
+        fileName.endsWith('.mjs') ||
+        fileName.endsWith('.cjs')
+    )
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}

package/package.json

@@ -1,13 +1,42 @@
 {
     "name": "@cratis/components.migrator",
-    "version": "0.0.0",
-    "description": "Reserved package record for the Cratis Components release workflow.",
+    "version": "4.1.0",
+    "description": "Migration tooling for updating @cratis/components consumers from Components 3 to Components 4.",
+    "author": "Cratis",
     "license": "MIT",
     "type": "module",
     "publishConfig": {
         "access": "public"
     },
+    "engines": {
+        "node": ">=20.0.0"
+    },
     "files": [
-        "README.md"
-    ]
+        "lib",
+        "scripts",
+        "README.md",
+        "LICENSE",
+        "compat-manifest.json"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Cratis/Components"
+    },
+    "exports": {
+        "./package.json": "./package.json"
+    },
+    "bin": {
+        "cratis-components-button-variant-tone": "./scripts/button-variant-tone.js",
+        "cratis-components-change-handler": "./scripts/change-handler.js",
+        "cratis-components-remove-root-namespace-imports": "./scripts/remove-root-namespace-imports.js"
+    },
+    "scripts": {
+        "test": "yarn g:test",
+        "verify-package": "node ./test/verify-packed-package.mjs",
+        "ci": "yarn g:test"
+    },
+    "dependencies": {
+        "semver": "7.8.5",
+        "typescript": "^6.0.3"
+    }
 }

package/scripts/button-variant-tone.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { transformButtonVariantTone } from '../lib/buttonVariantToneTransform.js';
+import { runTransformCli } from '../lib/runTransformCli.js';
+
+process.exitCode = runTransformCli(process.argv.slice(2), {
+    command: 'cratis-components-button-variant-tone',
+    description:
+        'Migrates deprecated Button text/link/outlined/rounded/severity JSX props to variant/tone/shape. Uncertain cases are annotated and reported for manual review.',
+    transform: transformButtonVariantTone,
+});

package/scripts/change-handler.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { transformChangeHandlers } from '../lib/changeHandlerTransform.js';
+import { runTransformCli } from '../lib/runTransformCli.js';
+
+process.exitCode = runTransformCli(process.argv.slice(2), {
+    command: 'cratis-components-change-handler',
+    description:
+        'Migrates structurally-proven Components event-wrapper callbacks to semantic value callbacks. Ambiguous handlers are annotated and reported for manual review.',
+    transform: transformChangeHandlers,
+});

package/scripts/remove-root-namespace-imports.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { runTransformCli } from '../lib/runTransformCli.js';
+import { transformSource } from '../lib/transform.js';
+
+process.exitCode = runTransformCli(process.argv.slice(2), {
+    command: 'cratis-components-remove-root-namespace-imports',
+    description:
+        'Rewrites Components 3 root namespace imports and named re-exports to Components 4 explicit subpaths. Unsupported whole-package and unknown forms are reported without guessing.',
+    transform: (file, text, { packageName }) =>
+        transformSource(file, text, { packageName }),
+});