@lablup/ui-common-cli 0.2.0-alpha.15

package/codemods/lib/todo.mjs

@@ -0,0 +1,151 @@
+/**
+ * Leave `TODO(ui-common-upgrade)` markers where a codemod could not prove a
+ * rewrite safe. Where the marker goes:
+ * - a JSX child gets a `{/* … *\/}` line right above it, or right before it
+ *   when it shares its line with other children;
+ * - an element that is a `return` value or a parenthesised expression gets a
+ *   `//` line right above it, inside the parentheses;
+ * - anything else gets a `//` line above its statement.
+ * A marker already there (from an earlier run) is not added twice.
+ * `ui-common upgrade` lists every marker in its report, with its line.
+ *
+ * A file whose transform calls `addTodo` is printed with `printSource`: the
+ * JSX-child markers are written into the printed text, not into the parent's
+ * `children`. Adding a child makes recast reprint the parent, and recast's
+ * reprint drops the leading whitespace of every text child
+ * (`{n} items` -> `{n}items`).
+ */
+import { TODO_TAG } from "./jsx.mjs";
+
+/** The markers waiting on a JSX child, written by `printSource`. */
+const PENDING = Symbol("ui-common-upgrade.todo");
+const SENTINEL = "__ui_common_upgrade_todo_";
+
+/** @param {any} node */
+function isStatement(node) {
+  return (
+    node &&
+    typeof node.type === "string" &&
+    /(Statement|Declaration)$/.test(node.type) &&
+    !node.type.startsWith("TS")
+  );
+}
+
+/** @param {any[] | undefined} comments @param {string} text */
+function hasComment(comments, text) {
+  return (comments ?? []).some((c) => String(c.value).trim() === text);
+}
+
+/** @param {any} node @param {string} text */
+function carries(node, text) {
+  return (
+    hasComment(node?.comments, text) ||
+    hasComment(node?.innerComments, text) ||
+    hasComment(node?.leadingComments, text)
+  );
+}
+
+/**
+ * @param {any} j jscodeshift
+ * @param {any} path NodePath of the node the message is about
+ * @param {string} message
+ */
+export function addTodo(j, path, message) {
+  const text = `${TODO_TAG}: ${message}`;
+  const node = path.node;
+  const parent = path.parent?.node;
+  const isElement = node.type === "JSXElement" || node.type === "JSXFragment";
+
+  if (
+    isElement &&
+    parent &&
+    (parent.type === "JSXElement" || parent.type === "JSXFragment") &&
+    Array.isArray(parent.children)
+  ) {
+    const index = parent.children.indexOf(node);
+    if (index === -1) return;
+    // Walk back over whitespace and earlier markers looking for this one.
+    for (let i = index - 1; i >= 0; i--) {
+      const sibling = parent.children[i];
+      if (sibling.type === "JSXText" && sibling.value.trim() === "") continue;
+      if (
+        sibling.type === "JSXExpressionContainer" &&
+        sibling.expression.type === "JSXEmptyExpression"
+      ) {
+        if (carries(sibling.expression, text)) return;
+        continue;
+      }
+      break;
+    }
+    const pending = (node[PENDING] ??= []);
+    if (!pending.includes(text)) pending.push(text);
+    return;
+  }
+
+  if (isElement && (parent?.type === "ReturnStatement" || node.extra?.parenthesized)) {
+    if (carries(node, text)) return;
+    node.comments = [...(node.comments ?? []), j.commentLine(` ${text}`, true, false)];
+    return;
+  }
+
+  let p = path;
+  while (p && !isStatement(p.node)) p = p.parent;
+  if (!p) return;
+  // An exported declaration carries the comment on the export, so it prints
+  // above `export`, not between `export` and the declaration.
+  if (p.parent && /^Export(Named|Default)Declaration$/.test(p.parent.node.type))
+    p = p.parent;
+  if (carries(p.node, text)) return;
+  p.node.comments = [
+    ...(p.node.comments ?? []),
+    j.commentLine(` ${text}`, true, false),
+  ];
+}
+
+/**
+ * `root.toSource(options)`, with the JSX-child markers `addTodo` left
+ * pending written in. Each marked element carries a sentinel block comment
+ * while it prints: a comment changes the element alone, so recast reprints
+ * neither the parent nor its text. The sentinel then becomes the marker:
+ * a `{/* … *\/}` line above an element that starts its line, or a
+ * `{/* … *\/}` right before one that follows other children on its line,
+ * with no whitespace added (the text renders as it did).
+ *
+ * @param {any} j jscodeshift
+ * @param {any} root the file's Collection
+ * @param {object} [options] recast print options
+ * @returns {string}
+ */
+export function printSource(j, root, options) {
+  /** @type {Map<string, string[]>} */
+  const markers = new Map();
+  for (const type of [j.JSXElement, j.JSXFragment]) {
+    root.find(type).forEach((/** @type {any} */ path) => {
+      const texts = path.node[PENDING];
+      if (!texts?.length) return;
+      const id = `${SENTINEL}${markers.size}__`;
+      markers.set(id, texts);
+      path.node.comments = [
+        ...(path.node.comments ?? []),
+        j.commentBlock(id, true, false),
+      ];
+    });
+  }
+  let out = root.toSource(options);
+  for (const [id, texts] of markers) {
+    const comment = `/*${id}*/`;
+    const at = out.indexOf(comment);
+    if (at === -1) throw new Error(`ui-common upgrade: lost the TODO marker ${id}`);
+    // Recast breaks the line after a leading comment; the element follows.
+    const after = at + comment.length;
+    const gap = /^\s*/.exec(out.slice(after))?.[0] ?? "";
+    const lineStart = out.lastIndexOf("\n", at - 1) + 1;
+    const indent = out.slice(lineStart, at);
+    const blocks = texts.map((text) => `{/* ${text} */}`);
+    const insert = /^[ \t]*$/.test(indent)
+      ? blocks.map((b) => `${b}\n${indent}`).join("")
+      : blocks.join("");
+    out = out.slice(0, at) + insert + out.slice(after + gap.length);
+  }
+  return out;
+}

package/codemods/registry.mjs

@@ -0,0 +1,95 @@
+/**
+ * The ui-common upgrade registry: codemod steps keyed by the ui-common version
+ * that introduced the change. `ui-common upgrade --from A --to B` runs every
+ * step with A < version <= B, in version order (semver precedence, so
+ * prerelease keys work: 0.1.0-alpha.19 < 0.2.0-alpha.0 < 0.2.0).
+ *
+ * Two kinds of step:
+ * - hand-written ones, listed in STATIC_STEPS (0.1 -> 0.2);
+ * - `codemods/<version>/upstream.json`, written by `ui-common sync-astryx`
+ *   when ui-common moves to a new Astryx: the Astryx codemods a consumer needs
+ *   for that bump, run through ./upstream.mjs.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compare, parse } from "../cli/semver.mjs";
+
+/**
+ * @typedef {object} Transform
+ * @property {string} id
+ * @property {string} title
+ * @property {string[]} extensions
+ * @property {boolean} [parse] re-parse the output as a script before accepting it
+ * @property {(file: {path: string, source: string}, api: {jscodeshift: any}, ctx: any) => string | null | undefined} run
+ *
+ * @typedef {object} Step
+ * @property {string} title
+ * @property {Transform[]} transforms
+ * @property {(ctx: any, api: {jscodeshift: any}) => void} [afterTransforms] project-level edits once every file is transformed
+ * @property {(text: string, ctx: any) => string | undefined} [packageJson]
+ * @property {(files: Array<[string, string]>) => any} [prepareScan] a context for `scan`, from every file it will read ([relative path, content])
+ * @property {(file: string, source: string, context?: any) => Array<{category: string, file: string, line: number, text: string, detail?: string}>} [scan]
+ * @property {(ctx: any, rel: (file: string) => string) => Array<{category: string, file: string, line: number, text: string, detail?: string}>} [findings] report findings the transforms collected, after they ran
+ * @property {Record<string, {title: string, help: string}>} [categories]
+ * @property {string[] | ((ctx: any) => string[])} [notes] report notes, or a function of the run
+ */
+
+export const CODEMODS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** @type {Array<{version: string, load: () => Promise<Step>}>} */
+const STATIC_STEPS = [
+  {
+    version: "0.2.0-alpha.0",
+    load: async () => (await import("./0.2/index.mjs")).default,
+  },
+];
+
+/** Upstream steps recorded by `sync-astryx`: `codemods/<version>/upstream.json`. */
+export function upstreamManifests() {
+  if (!existsSync(CODEMODS_DIR)) return [];
+  return readdirSync(CODEMODS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && parse(e.name) && /^\d+\.\d+\.\d+/.test(e.name))
+    .map((e) => ({
+      version: e.name,
+      file: join(CODEMODS_DIR, e.name, "upstream.json"),
+    }))
+    .filter((m) => existsSync(m.file));
+}
+
+/** Every registered version, ascending. */
+export function registeredVersions() {
+  const versions = new Set([
+    ...STATIC_STEPS.map((s) => s.version),
+    ...upstreamManifests().map((m) => m.version),
+  ]);
+  return [...versions].sort(compare);
+}
+
+/**
+ * The steps to run for `from` (exclusive) to `to` (inclusive).
+ *
+ * @param {string} from
+ * @param {string} to
+ * @returns {Promise<Array<{version: string, step: Step}>>}
+ */
+export async function stepsBetween(from, to) {
+  /** @type {Array<{version: string, step: Step}>} */
+  const out = [];
+  for (const version of registeredVersions()) {
+    if (compare(version, from) <= 0 || compare(version, to) > 0) continue;
+    for (const s of STATIC_STEPS.filter((x) => x.version === version)) {
+      out.push({ version, step: await s.load() });
+    }
+    const upstream = upstreamManifests().find((m) => m.version === version);
+    if (upstream) {
+      const { upstreamStep } = await import("./upstream.mjs");
+      out.push({
+        version,
+        step: await upstreamStep(JSON.parse(readFileSync(upstream.file, "utf8"))),
+      });
+    }
+  }
+  return out;
+}

package/codemods/upstream.mjs

@@ -0,0 +1,155 @@
+/**
+ * Run Astryx's own codemods on a ui-common consumer.
+ *
+ * Astryx codemods match `@astryxdesign/*` import specifiers; a ui-common
+ * consumer imports the same modules as `@lablup/ui-common/*`. So each
+ * transform sees the file with the module specifiers swapped to Astryx's, and
+ * its output's module specifiers are swapped back. Only specifiers are
+ * swapped (imports, re-exports, `import()`, `require()`): a comment or string
+ * that names either package is left as written. A file the transform does not
+ * change is left alone.
+ *
+ * `codemods/<ui-common version>/upstream.json` (written by
+ * `ui-common sync-astryx`) names the Astryx version range and codemod ids.
+ */
+import { importAstryxInternal } from "../cli/paths.mjs";
+import { rewriteSpecifiers } from "../cli/rewrite.mjs";
+
+const DEFAULT_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs"];
+
+/**
+ * `@lablup/ui-common/…` -> the `@astryxdesign/…` specifier Astryx's codemods
+ * look for. The inverse is rewriteSpecifiers.
+ *
+ * @param {string} text
+ */
+export function toAstryxSpecifiers(text) {
+  return text
+    .replace(/@lablup\/ui-common\/lab(?=[/"'`\s),;:]|$)/g, "@astryxdesign/lab")
+    .replace(
+      /@lablup\/ui-common\/theme\/neutral(?=[/"'`\s),;:]|$)/g,
+      "@astryxdesign/theme-neutral",
+    )
+    .replace(/@lablup\/ui-common(?=[/"'`\s),;:]|$)/g, "@astryxdesign/core");
+}
+
+/**
+ * Apply `swap` to the module specifier strings of a script and nothing else.
+ * A source jscodeshift cannot parse (a stylesheet an Astryx codemod targets)
+ * is swapped as a whole.
+ *
+ * @param {any} j
+ * @param {string} source
+ * @param {(text: string) => string} swap
+ */
+export function swapModuleSpecifiers(j, source, swap) {
+  let root;
+  try {
+    root = j(source);
+  } catch {
+    return swap(source);
+  }
+  /** @type {Array<{start: number, end: number}>} */
+  const ranges = [];
+  const add = (/** @type {any} */ node) => {
+    const isString =
+      node?.type === "StringLiteral" ||
+      (node?.type === "Literal" && typeof node.value === "string");
+    if (isString && typeof node.start === "number" && typeof node.end === "number")
+      ranges.push({ start: node.start, end: node.end });
+  };
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ p) => add(p.node.source));
+  root
+    .find(j.ExportNamedDeclaration)
+    .forEach((/** @type {any} */ p) => add(p.node.source));
+  root
+    .find(j.ExportAllDeclaration)
+    .forEach((/** @type {any} */ p) => add(p.node.source));
+  root.find(j.CallExpression).forEach((/** @type {any} */ p) => {
+    const callee = p.node.callee;
+    const isImport = callee.type === "Import";
+    const isRequire = callee.type === "Identifier" && callee.name === "require";
+    if (isImport || isRequire) add(p.node.arguments[0]);
+  });
+  if (j.ImportExpression)
+    root.find(j.ImportExpression).forEach((/** @type {any} */ p) => add(p.node.source));
+  if (j.TSImportType)
+    root.find(j.TSImportType).forEach((/** @type {any} */ p) => {
+      add(p.node.argument?.literal ?? p.node.argument);
+    });
+  let out = source;
+  for (const { start, end } of ranges.sort((a, b) => b.start - a.start)) {
+    out = `${out.slice(0, start)}${swap(out.slice(start, end))}${out.slice(end)}`;
+  }
+  return out;
+}
+
+/**
+ * @typedef {{astryx: {from: string, to: string}, codemods: Array<{id: string, version: string, title?: string}>}} UpstreamManifest
+ */
+
+/**
+ * @param {{name: string, transform: Function, meta: {title: string, fileExtensions?: string[], codemodType?: string}}} entry
+ * @param {string} version Astryx version the codemod belongs to
+ * @returns {import('./registry.mjs').Transform}
+ */
+export function wrapAstryxTransform(entry, version) {
+  const extensions = entry.meta.fileExtensions ?? DEFAULT_EXTENSIONS;
+  return {
+    id: `astryx:${entry.name}`,
+    title: `Astryx ${version}: ${entry.meta.title}`,
+    extensions,
+    parse: extensions.some((e) => DEFAULT_EXTENSIONS.includes(e)),
+    run(file, api) {
+      const j = api.jscodeshift;
+      const swapped = swapModuleSpecifiers(j, file.source, toAstryxSpecifiers);
+      const out = entry.transform(
+        { path: file.path, source: swapped },
+        { jscodeshift: j, stats: () => {}, report: () => {} },
+      );
+      if (out == null || out === swapped) return undefined;
+      return swapModuleSpecifiers(j, out, rewriteSpecifiers);
+    },
+  };
+}
+
+/**
+ * @param {UpstreamManifest} manifest
+ * @returns {Promise<import('./registry.mjs').Step>}
+ */
+export async function upstreamStep(manifest) {
+  const { getTransformsBetween } = await importAstryxInternal(
+    "assets/codemods/registry.mjs",
+  );
+  const groups = await getTransformsBetween(manifest.astryx.from, manifest.astryx.to);
+  /** @type {Map<string, {entry: any, version: string}>} */
+  const byName = new Map();
+  for (const group of groups) {
+    for (const entry of group.transforms)
+      byName.set(entry.name, { entry, version: group.version });
+  }
+  const notes = [];
+  /** @type {import('./registry.mjs').Transform[]} */
+  const transforms = [];
+  for (const codemod of manifest.codemods) {
+    const found = byName.get(codemod.id);
+    if (!found) {
+      notes.push(
+        `Astryx codemod "${codemod.id}" (${codemod.version}) is not in the installed @astryxdesign/cli; run it by hand if you use what it migrates.`,
+      );
+      continue;
+    }
+    if (found.entry.meta?.codemodType === "config") {
+      notes.push(
+        `Astryx codemod "${codemod.id}" edits astryx.config.*; run \`ui-common astryx upgrade\` if you keep one.`,
+      );
+      continue;
+    }
+    transforms.push(wrapAstryxTransform(found.entry, found.version));
+  }
+  return {
+    title: `Astryx ${manifest.astryx.from} → ${manifest.astryx.to} codemods`,
+    transforms,
+    notes,
+  };
+}