@wallarm-org/migrator 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @wallarm-org/migrator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Codemod CLI that migrates consumer apps across `@wallarm-org/design-system` breaking changes. Renovate runs it after a design-system upgrade; it can also be run by hand.
+
+## How an upgrade reaches your app
+
+1. The design-system releases a new version. Breaking changes always come in a major, and every breaking change ships a migration.
+2. Renovate opens one MR in your repo with the version bump, the lockfile, and the source rewrites made by the migrator. It applies every migration between the version you were on and the new one, so skipping several majors is fine.
+3. Whatever the migrator can rewrite safely is already done in the MR. Whatever it can't — a value computed at runtime, a spread that may override the prop — it leaves for you, marked in the code and listed in `wds-migration.md`. It never guesses: after the MR your app renders the same as before the upgrade.
+4. Your CI fails while any manual step is left, so the MR can't be merged half-migrated.
+
+## Fixing manual steps
+
+Each spot that needs you gets a marker right after the component name, saying which migration left it and what to do:
+
+```tsx
+// In the MR
+<Avatar /* @wds-migration(avatar-size-rename): Avatar size was renamed (xs -> md, sm -> lg; new sm is 20px): non-static value, review manually */ size={big ? 'sm' : 'xs'} />
+
+// After you fix it (old sm is the new lg, old xs is the new md)
+<Avatar size={big ? 'lg' : 'md'} />
+```
+
+`wds-migration.md` (one per package in a monorepo) lists the same spots with file and line, plus files that could not be parsed. Fix every marker, delete the comment and the report, push — CI goes green.
+
+## Usage
+
+```bash
+migrator --from <version> [--to <version>] [--dry-run] [paths...]
+```
+
+- `--from` (required): the exact stable design-system version you are migrating from. A prerelease `--from` is rejected: pass the stable version your code matches.
+- `--to`: target version (default: the installed `@wallarm-org/design-system`).
+- `--dry-run`: print changes, write nothing.
+- `--help`, `--version`.
+
+Without paths, tracked files under the current directory are scanned. Exit code is `0` for completed runs (even with manual items) and `1` for usage/version errors. When something needs a manual change, or a file could not be parsed, `wds-migration.md` is written (its heading contains `@wds-migration`), and each manual spot also gets an in-code marker right after the tag name: `<Avatar /* @wds-migration(avatar-size-rename): … */ size={s} />`.
+
+## Consumer setup
+
+Renovate repository config (or a shared preset in the GitLab Renovate runner repo):
+
+```json
+{
+  "packageRules": [
+    {
+      "matchPackageNames": ["@wallarm-org/design-system"],
+      "minimumReleaseAge": "1 hour",
+      "prBodyNotes": ["⚠️ The design-system migrator may have left manual steps: search this MR for `wds-migration` comments and the `wds-migration.md` report, fix them, then delete the report."],
+      "postUpgradeTasks": {
+        "commands": ["npx --yes @wallarm-org/migrator@latest --from {{{currentVersion}}} --to {{{newVersion}}}"],
+        "fileFilters": ["**/*.{ts,tsx,js,jsx,mts,cts}", "**/wds-migration.md"],
+        "workingDirTemplate": "{{{packageFileDir}}}",
+        "installTools": { "node": {} }
+      }
+    }
+  ]
+}
+```
+
+- `workingDirTemplate` runs the migrator from each upgraded `package.json`'s directory, so each package's tasks run with its own `--from` and only touch files under it. From the repo root, one package's `--from` would rewrite every package (e.g. turn an already-migrated `sm` into `lg`). In a monorepo each package gets its own `wds-migration.md`, hence the recursive filter and CI check.
+- `currentVersion` is the **locked** version when a lockfile exists (Renovate has no separate `lockedVersion` template). Consumers must commit their lockfile.
+- `installTools.node` is needed on the default slim Renovate image (`binarySource=install`), where `npx` isn't on PATH. The `-full` image already has it. With `binarySource=global` the runner image has to provide node/npm.
+- Self-hosted runner admin config: `allowedCommands: ["^npx --yes @wallarm-org/migrator@latest --from \\d+\\.\\d+\\.\\d+\\S* --to \\d+\\.\\d+\\.\\d+\\S*$"]`.
+- `prBodyNotes` deliberately avoids the literal `@wds-migration`: the tracked Renovate config would otherwise trip the CI gate below.
+- Consumer CI: one job
+
+  ```sh
+  if git grep -n '@wds-migration'; then echo 'Design-system migration left manual steps: fix the @wds-migration markers and delete wds-migration.md'; exit 1; fi
+  ```
+
+  Both the in-code markers and the report heading contain `@wds-migration`, so it fails (and prints the hits) until every marker is fixed and `wds-migration.md` is deleted; it works under `set -e`.
+- Manual run after an upgrade: `pnpm dlx @wallarm-org/migrator --from 2.9.0` (or `yarn dlx` / `npx`).
+
+## Adding a migration
+
+In Claude Code, run `/new-migration`: it walks through finding the breaking changes, deriving the mapping and writing the tests.
+
+Every breaking-change PR to the design-system must add a migration (enforced by `require-migration` in `.github/workflows/pr-title.yml`). A breaking change that needs nothing from consumers ships a report-only migration.
+
+1. Create `src/migrations/<id>.ts` exporting `migration: Migration` (`{ id, title, transform(file, ctx) }`). Use `ctx.report(node, message)` for cases that need a manual change, and the JSX helpers in `src/lib/jsx.ts`.
+2. Register it in `src/migrations/index.ts`.
+3. Add before/after fixtures in `src/migrations/__fixtures__/<id>/<case>.input.tsx` + `<case>.output.tsx` (outputs include the `@wds-migration` markers; `__tests__/fixtures.test.ts` also checks idempotence). Assert report counts/messages, aliased/subpath/namespace imports and a same-named non-DS component (must not change) in `src/migrations/__tests__/` using `apply()` from `harness.ts`.
+4. Never edit `versions.json` by hand: it is stamped automatically when the design-system releases a major version.

package/dist/index.js

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { execFileSync } from "node:child_process";
+import { Node, Project, SyntaxKind, ts } from "ts-morph";
+import { clean, gt, lt, lte, major, prerelease, valid } from "semver";
+class UsageError extends Error {
+}
+const SOURCE_EXTENSIONS = [
+    'ts',
+    'tsx',
+    'js',
+    'jsx',
+    'mts',
+    'cts'
+];
+const isSource = (f)=>SOURCE_EXTENSIONS.some((e)=>f.endsWith(`.${e}`));
+function walk(abs, out) {
+    const stat = node_fs.statSync(abs, {
+        throwIfNoEntry: false
+    });
+    if (!stat) throw new UsageError(`path not found: ${abs}`);
+    if (stat.isFile()) {
+        if (isSource(abs)) out.push(abs);
+        return;
+    }
+    for (const entry of node_fs.readdirSync(abs, {
+        withFileTypes: true
+    }))if ('node_modules' !== entry.name && '.git' !== entry.name) walk(node_path.join(abs, entry.name), out);
+}
+function listCandidateFiles(cwd, paths) {
+    const out = [];
+    if (paths.length > 0) {
+        for (const p of paths)walk(node_path.resolve(cwd, p), out);
+        return out;
+    }
+    try {
+        const stdout = execFileSync('git', [
+            'ls-files',
+            '-z',
+            '--',
+            ...SOURCE_EXTENSIONS.map((e)=>`*.${e}`)
+        ], {
+            cwd,
+            encoding: 'utf8',
+            stdio: [
+                'ignore',
+                'pipe',
+                'ignore'
+            ],
+            maxBuffer: 268435456
+        });
+        return stdout.split('\0').filter(Boolean).map((f)=>node_path.resolve(cwd, f));
+    } catch  {
+        throw new UsageError('not a git repository: pass explicit paths (e.g. `migrator --from X src`)');
+    }
+}
+const REPORT_FILE = 'wds-migration.md';
+function renderReport(args) {
+    const lines = [
+        '# Design-system migration: manual steps (@wds-migration)',
+        '',
+        `The automatic migration from ${args.from} to ${args.to} left these items for you:`,
+        '',
+        ...args.manual.map((m)=>`- [ ] \`${m.file}:${m.line}\` — ${m.message} (${m.migrationId})`),
+        ''
+    ];
+    if (args.skipped.length > 0) lines.push('## Files that could not be parsed', '', ...args.skipped.map((s)=>`- \`${s.file}\` — ${s.error}`), '');
+    lines.push('Delete this file once every item is done.', '');
+    return lines.join('\n');
+}
+const DS_PACKAGE = '@wallarm-org/design-system';
+function createProject() {
+    return new Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: {
+            allowJs: true,
+            jsx: ts.JsxEmit.Preserve
+        }
+    });
+}
+function localTagNames(file, component) {
+    const names = new Set();
+    for (const decl of file.getImportDeclarations()){
+        const spec = decl.getModuleSpecifierValue();
+        if (spec !== DS_PACKAGE && spec !== `${DS_PACKAGE}/${component}`) continue;
+        for (const named of decl.getNamedImports())if (named.getName() === component) names.add(named.getAliasNode()?.getText() ?? component);
+        const ns = decl.getNamespaceImport();
+        if (ns) names.add(`${ns.getText()}.${component}`);
+    }
+    return names;
+}
+function findComponentElements(file, component) {
+    const names = localTagNames(file, component);
+    if (0 === names.size) return [];
+    return [
+        ...file.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+        ...file.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement)
+    ].filter((el)=>names.has(el.getTagNameNode().getText()));
+}
+function getAttribute(el, name) {
+    const attr = el.getAttribute(name);
+    return attr && Node.isJsxAttribute(attr) ? attr : void 0;
+}
+function hasSpread(el) {
+    return el.getAttributes().some((a)=>Node.isJsxSpreadAttribute(a));
+}
+function hasSpreadAfter(el, attr) {
+    const attrs = el.getAttributes();
+    return attrs.slice(attrs.indexOf(attr) + 1).some((a)=>Node.isJsxSpreadAttribute(a));
+}
+function staticLiteral(attr) {
+    const init = attr.getInitializer();
+    const inner = init && Node.isJsxExpression(init) ? init.getExpression() : init;
+    return inner && (Node.isStringLiteral(inner) || Node.isNoSubstitutionTemplateLiteral(inner)) ? inner : void 0;
+}
+function readStaticString(attr) {
+    return staticLiteral(attr)?.getLiteralValue();
+}
+function replaceStaticString(attr, value) {
+    const lit = staticLiteral(attr);
+    if (!lit) return;
+    const delim = lit.getText()[0];
+    lit.replaceWithText(`${delim}${value}${delim}`);
+}
+const SYNTAX_ERROR = 'syntax error, file left untouched';
+function markerTarget(node) {
+    return Node.isJsxOpeningElement(node) || Node.isJsxSelfClosingElement(node) ? node : node.getFirstAncestor((a)=>Node.isJsxOpeningElement(a) || Node.isJsxSelfClosingElement(a));
+}
+function markerRegion(el) {
+    const end = el.getAttributes()[0]?.getStart() ?? el.getEnd();
+    return el.getSourceFile().getFullText().slice(el.getTagNameNode().getEnd(), end);
+}
+function migrateSource(args) {
+    const project = args.project ?? createProject();
+    const sourceFile = project.createSourceFile(args.fileName, args.text, {
+        overwrite: true
+    });
+    try {
+        return applyMigrations(project, sourceFile, args.migrations);
+    } finally{
+        sourceFile.forget();
+    }
+}
+function applyMigrations(project, sourceFile, migrations) {
+    if (project.getProgram().getSyntacticDiagnostics(sourceFile).length > 0) throw new Error(SYNTAX_ERROR);
+    const manual = [];
+    for (const migration of migrations){
+        const token = `@wds-migration(${migration.id})`;
+        const pending = new Map();
+        migration.transform(sourceFile, {
+            report: (node, message)=>{
+                manual.push({
+                    line: node.getStartLineNumber(),
+                    migrationId: migration.id,
+                    message
+                });
+                const el = markerTarget(node);
+                if (el && !pending.has(el) && !markerRegion(el).includes(token)) pending.set(el, message);
+            }
+        });
+        const inserts = [
+            ...pending
+        ].map(([el, message])=>({
+                pos: el.getTagNameNode().getEnd(),
+                text: ` /* ${token}: ${message.replaceAll('*/', '* /').replace(/[\r\n]+/g, ' ')} */`
+            })).sort((x, y)=>y.pos - x.pos);
+        for (const { pos, text } of inserts)sourceFile.insertText(pos, text);
+    }
+    return {
+        code: sourceFile.getFullText(),
+        manual
+    };
+}
+function runMigrations(args) {
+    const result = {
+        changed: [],
+        manual: [],
+        skipped: []
+    };
+    const project = createProject();
+    for (const abs of args.files){
+        const file = node_path.relative(args.cwd, abs).split(node_path.sep).join('/');
+        try {
+            const before = node_fs.readFileSync(abs, 'utf8');
+            if (!before.includes(DS_PACKAGE)) continue;
+            const { code: after, manual } = migrateSource({
+                text: before,
+                fileName: file,
+                migrations: args.migrations,
+                project
+            });
+            result.manual.push(...manual.map((m)=>({
+                    file,
+                    ...m
+                })));
+            if (after !== before) result.changed.push({
+                file,
+                before,
+                after
+            });
+        } catch (e) {
+            result.skipped.push({
+                file,
+                error: e instanceof Error ? e.message : String(e)
+            });
+        }
+    }
+    return result;
+}
+function parseExactVersion(input, flag) {
+    const version = valid(clean(input));
+    if (!version) throw new UsageError(`${flag} must be an exact version (e.g. 2.9.0), got "${input}"`);
+    if ('--from' === flag && prerelease(version)) throw new UsageError(`--from ${version} is a prerelease; pass the stable version your code matches`);
+    return version;
+}
+function selectMigrations(args) {
+    const { from, to, versions, migrations } = args;
+    if (lt(from, '1.0.0')) throw new UsageError(`--from ${from} is too old: upgrade to 1.x manually first`);
+    if (gt(from, to)) throw new UsageError(`--from ${from} is newer than --to ${to}`);
+    const isPrerelease = null !== prerelease(to);
+    if (!isPrerelease && major(to) > major(versions.latest)) throw new UsageError(`design-system ${to} is newer than this migrator knows; retry later or update @wallarm-org/migrator`);
+    const stamped = migrations.flatMap((m)=>{
+        const v = versions.migrations[m.id];
+        return void 0 === v ? [] : [
+            {
+                m,
+                v
+            }
+        ];
+    }).filter(({ v })=>gt(v, from) && lte(v, to)).sort((x, y)=>gt(x.v, y.v) ? 1 : gt(y.v, x.v) ? -1 : x.m.id.localeCompare(y.m.id)).map(({ m })=>m);
+    const pending = isPrerelease ? migrations.filter((m)=>!(m.id in versions.migrations)).sort((x, y)=>x.id.localeCompare(y.id)) : [];
+    return [
+        ...stamped,
+        ...pending
+    ];
+}
+const RENAMES = {
+    xs: 'md',
+    sm: 'lg'
+};
+const HINT = 'Avatar size was renamed (xs -> md, sm -> lg; new sm is 20px)';
+const avatar_size_rename_migration = {
+    id: 'avatar-size-rename',
+    title: 'Avatar: xs → md, sm → lg',
+    transform (file, ctx) {
+        for (const el of findComponentElements(file, 'Avatar')){
+            const attr = getAttribute(el, 'size');
+            if (attr) {
+                const value = readStaticString(attr);
+                const next = void 0 === value ? void 0 : RENAMES[value];
+                if (void 0 === value) ctx.report(attr, `${HINT}: non-static value, review manually`);
+                else if (next && Object.hasOwn(RENAMES, value)) replaceStaticString(attr, next);
+                if (void 0 !== value && hasSpreadAfter(el, attr)) ctx.report(attr, `${HINT}: spread props after size may override it with an old value, review manually`);
+            } else if (hasSpread(el)) ctx.report(el, `${HINT}: size may come from spread props, review manually`);
+        }
+    }
+};
+const MAP = {
+    primary: [
+        'secondary',
+        'neutral'
+    ],
+    'primary-alt': [
+        'secondary',
+        'neutral-alt'
+    ],
+    brand: [
+        'solid',
+        'brand'
+    ],
+    destructive: [
+        'solid',
+        'danger'
+    ],
+    outline: [
+        'outline',
+        'neutral'
+    ],
+    info: [
+        'secondary',
+        'info'
+    ]
+};
+const NEW_TYPES = new Set([
+    'solid',
+    'secondary',
+    'outline'
+]);
+const numeric_badge_type_color_HINT = 'NumericBadge type was split into type + color';
+const numeric_badge_type_color_migration = {
+    id: 'numeric-badge-type-color',
+    title: 'NumericBadge: type splits into type + color',
+    transform (file, ctx) {
+        for (const el of findComponentElements(file, 'NumericBadge')){
+            const typeAttr = getAttribute(el, 'type');
+            if (!typeAttr) {
+                if (hasSpread(el)) ctx.report(el, `${numeric_badge_type_color_HINT}: type may come from spread props, review manually`);
+                continue;
+            }
+            const value = readStaticString(typeAttr);
+            if (void 0 === value) {
+                ctx.report(typeAttr, `${numeric_badge_type_color_HINT}: non-static type, review manually`);
+                continue;
+            }
+            if (hasSpreadAfter(el, typeAttr)) ctx.report(typeAttr, `${numeric_badge_type_color_HINT}: spread props after type may override it with an old value, review manually`);
+            if (!Object.hasOwn(MAP, value)) continue;
+            if (getAttribute(el, 'color')) {
+                if (!NEW_TYPES.has(value)) ctx.report(typeAttr, `${numeric_badge_type_color_HINT}: already has color, review manually`);
+                continue;
+            }
+            const [type, color] = MAP[value];
+            const q = typeAttr.getText().match(/['"]/)?.[0] ?? "'";
+            replaceStaticString(typeAttr, type);
+            typeAttr.replaceWithText(`${typeAttr.getText()} color=${q}${color}${q}`);
+        }
+    }
+};
+const migrations_migrations = [
+    numeric_badge_type_color_migration,
+    avatar_size_rename_migration
+];
+const USAGE = `Usage: migrator --from <version> [--to <version>] [--dry-run] [paths...]
+
+Migrates a consumer app across @wallarm-org/design-system breaking changes.
+
+Options:
+  --from <version>  design-system version you are migrating from (required, exact)
+  --to <version>    target version (default: installed @wallarm-org/design-system)
+  --dry-run         print changes, write nothing
+  --help            show this help
+  --version         show migrator version
+
+Without paths, tracked files of the current git repository are scanned.`;
+function installedVersion(cwd) {
+    for(let dir = cwd;; dir = node_path.dirname(dir)){
+        const file = node_path.join(dir, 'node_modules/@wallarm-org/design-system/package.json');
+        if (node_fs.existsSync(file)) return JSON.parse(node_fs.readFileSync(file, 'utf8')).version;
+        if (node_path.dirname(dir) === dir) throw new UsageError('could not find installed @wallarm-org/design-system: pass --to');
+    }
+}
+function lineDiff(before, after) {
+    const a = before.split('\n');
+    const b = after.split('\n');
+    const lines = [];
+    for(let i = 0; i < Math.max(a.length, b.length); i++)if (a[i] !== b[i]) lines.push(`  L${i + 1}: ${a[i]?.trim() ?? ''} → ${b[i]?.trim() ?? ''}`);
+    return lines;
+}
+async function main(argv, cwd, versions, version, io = {
+    log: console.log,
+    error: console.error
+}) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            options: {
+                from: {
+                    type: 'string'
+                },
+                to: {
+                    type: 'string'
+                },
+                'dry-run': {
+                    type: 'boolean'
+                },
+                help: {
+                    type: 'boolean'
+                },
+                version: {
+                    type: 'boolean'
+                }
+            },
+            allowPositionals: true,
+            strict: true
+        });
+        if (values.help) {
+            io.log(USAGE);
+            return 0;
+        }
+        if (values.version) {
+            io.log(version);
+            return 0;
+        }
+        if (void 0 === values.from) throw new UsageError('--from is required');
+        const from = parseExactVersion(values.from, '--from');
+        const to = parseExactVersion(values.to ?? installedVersion(cwd), '--to');
+        const selected = selectMigrations({
+            from,
+            to,
+            versions,
+            migrations: migrations_migrations
+        });
+        const files = listCandidateFiles(cwd, positionals);
+        const { changed, manual, skipped } = runMigrations({
+            files,
+            cwd,
+            migrations: selected
+        });
+        const dry = true === values['dry-run'];
+        for (const c of changed)if (dry) {
+            io.log(c.file);
+            for (const l of lineDiff(c.before, c.after))io.log(l);
+        } else node_fs.writeFileSync(node_path.join(cwd, c.file), c.after);
+        for (const s of skipped)io.error(`warning: skipped ${s.file}: ${s.error}`);
+        const writeReport = !dry && (manual.length > 0 || skipped.length > 0);
+        if (writeReport) node_fs.writeFileSync(node_path.join(cwd, REPORT_FILE), renderReport({
+            from,
+            to,
+            manual,
+            skipped
+        }));
+        const s = (n, w)=>`${n} ${w}${1 === n ? '' : 's'}`;
+        io.log(`${dry ? '[dry-run] ' : ''}${s(changed.length, 'file')} changed, ${s(manual.length, 'manual item')}` + (skipped.length ? `, ${s(skipped.length, 'file')} skipped` : '') + (writeReport ? `; see ${REPORT_FILE}` : ''));
+        return 0;
+    } catch (e) {
+        if (e instanceof UsageError || e?.code?.startsWith('ERR_PARSE_ARGS')) {
+            io.error(e.message);
+            return 1;
+        }
+        throw e;
+    }
+}
+const root = node_path.join(node_path.dirname(fileURLToPath(import.meta.url)), '..');
+const readJson = (f)=>JSON.parse(node_fs.readFileSync(node_path.join(root, f), 'utf8'));
+const src_versions = readJson('versions.json');
+process.exitCode = await main(process.argv.slice(2), process.cwd(), src_versions, readJson('package.json').version);

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@wallarm-org/migrator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Codemod CLI that migrates consumer apps across Wallarm Design System breaking changes",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wallarm/design-system.git",
+    "directory": "packages/migrator"
+  },
+  "license": "MIT",
+  "author": "Wallarm",
+  "type": "module",
+  "bin": {
+    "migrator": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "versions.json"
+  ],
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "rstest watch",
+    "test:run": "rstest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "prepare-publish",
+    "postpublish": "restore-package"
+  },
+  "dependencies": {
+    "semver": "7.8.5",
+    "ts-morph": "28.0.0"
+  },
+  "devDependencies": {
+    "@rslib/core": "catalog:",
+    "@rstest/core": "catalog:",
+    "@types/node": "catalog:",
+    "@types/semver": "7.8.0",
+    "@wallarm-org/publish-scripts": "workspace:*",
+    "@wallarm-org/rstest-config": "workspace:*",
+    "@wallarm-org/typescript-config": "workspace:*",
+    "typescript": "catalog:"
+  }
+}

package/versions.json

@@ -0,0 +1 @@
+{ "latest": "3.0.0", "migrations": { "numeric-badge-type-color": "2.0.0", "avatar-size-rename": "3.0.0" } }