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

package/cli/rewrite.mjs

@@ -0,0 +1,133 @@
+/**
+ * Rewrite Astryx CLI output into ui-common terms.
+ *
+ * Every replacement is a plain substring swap between two strings that contain
+ * no quote, backslash or control character, so it is safe inside JSON string
+ * literals: `--json` output stays valid JSON.
+ */
+import { forkedExports, hiddenExports } from "./paths.mjs";
+
+/** Astryx CLI subcommands. Used to tell `astryx component` from `astryx-base`. */
+export const ASTRYX_COMMANDS = [
+  "init",
+  "component",
+  "docs",
+  "blog",
+  "swizzle",
+  "gap-report",
+  "template",
+  "layout",
+  "upgrade",
+  "theme",
+  "integration",
+  "hook",
+  "discover",
+  "search",
+  "build",
+  "doctor",
+  "manifest",
+  "help",
+];
+
+const SPECIFIERS = [
+  // Order matters: the bare package names last, so they never eat a subpath.
+  [/@astryxdesign\/core(?=[/"'`\s),;:]|$)/g, "@lablup/ui-common"],
+  [/@astryxdesign\/lab(?=[/"'`\s),;:]|$)/g, "@lablup/ui-common/lab"],
+  [
+    /@astryxdesign\/theme-neutral(?=[/"'`\s),;:]|$)/g,
+    "@lablup/ui-common/theme/neutral",
+  ],
+];
+
+/**
+ * `@astryxdesign/core/Button` -> `@lablup/ui-common/Button`, and the lab and
+ * neutral-theme packages onto their ui-common mirrors.
+ *
+ * @param {string} text
+ */
+export function rewriteSpecifiers(text) {
+  let out = text;
+  for (const [pattern, replacement] of SPECIFIERS) {
+    out = out.replace(
+      /** @type {RegExp} */ (pattern),
+      /** @type {string} */ (replacement),
+    );
+  }
+  return out;
+}
+
+/**
+ * `pnpm exec astryx component X` -> `<invocation> component X`, and a bare
+ * `astryx component` in prose -> `ui-common component`. `astryx-base`,
+ * `astryx.css` and `.astryx-badge` are left alone: only the bin followed by a
+ * real subcommand is rewritten.
+ *
+ * @param {string} text
+ * @param {string} invocation how the project runs the ui-common bin
+ */
+export function rewriteCommands(text, invocation = "ui-common") {
+  const commands = ASTRYX_COMMANDS.join("|");
+  return (
+    text
+      // A one-off `npx @astryxdesign/cli` invocation, or an installed-bin
+      // invocation through a package manager.
+      .replace(
+        /\b(?:npx|pnpm dlx|yarn dlx|bunx) @astryxdesign\/cli(?=[\s`'"]|$)/g,
+        invocation,
+      )
+      .replace(
+        /\b(?:npx|pnpm exec|pnpm|yarn|bunx|bun x|npm exec)\s+astryx(?=[\s`'"]|$)/g,
+        invocation,
+      )
+      .replace(
+        new RegExp(String.raw`(?<![\w/@.\-])astryx(?= (?:${commands})\b)`, "g"),
+        "ui-common",
+      )
+  );
+}
+
+/**
+ * Lines telling the reader that a name they are looking at is one ui-common
+ * hides, and what to use instead; or one ui-common exports from its own copy
+ * of the Astryx component, and what that copy changes.
+ *
+ * @param {string} text rewritten output
+ * @param {string[]} args the command line, so `component Dialog` is caught
+ *   even when the output never spells the name
+ */
+export function exclusionNotes(text, args = []) {
+  const notes = [];
+  const mentions = (name) =>
+    new RegExp(String.raw`(?<![\w.-])${name}(?![\w.-])`).test(text) ||
+    args.includes(name);
+  for (const entry of hiddenExports()) {
+    // Asking about the replacement itself needs no pointer to it.
+    if (!entry.replacedBy || args.includes(entry.replacedBy)) continue;
+    const name = entry.name;
+    if (mentions(name)) {
+      notes.push(
+        `Note: @lablup/ui-common does not export ${name}. Use ${entry.replacedBy} ` +
+          `(@lablup/ui-common/${entry.replacedBy}), not ${name}. ${entry.reason}`,
+      );
+    }
+  }
+  for (const fork of forkedExports()) {
+    if (fork.names.some(mentions)) {
+      notes.push(
+        `Note: ${fork.name} (${fork.from}) comes from ui-common: its own copy of ` +
+          `Astryx's, same API and import path. ${fork.reason}`,
+      );
+    }
+  }
+  return notes;
+}
+
+/**
+ * The full output rewrite: specifiers, then command invocations.
+ *
+ * @param {string} text
+ * @param {string} [invocation]
+ */
+export function rewriteOutput(text, invocation) {
+  return rewriteCommands(rewriteSpecifiers(text), invocation);
+}

package/cli/semver.mjs

@@ -0,0 +1,278 @@
+/**
+ * The little semver the upgrade registry needs: parse, compare with
+ * prerelease precedence, and coerce the loose forms a person types
+ * (`0.1`, `v0.1.0-alpha.19`) or a package.json holds (`^0.1.0-alpha.7`).
+ */
+
+const SEMVER =
+  /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/**
+ * @param {string} input
+ * @returns {{major: number, minor: number, patch: number, pre: string[]} | null}
+ */
+export function parse(input) {
+  const match = SEMVER.exec(String(input).trim());
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0),
+    pre: match[4] ? match[4].split(".") : [],
+  };
+}
+
+/** @param {{major: number, minor: number, patch: number, pre: string[]}} v */
+export function format(v) {
+  return `${v.major}.${v.minor}.${v.patch}${v.pre.length ? `-${v.pre.join(".")}` : ""}`;
+}
+
+/**
+ * The first version a dependency spec admits, for `^0.1.0-alpha.7`,
+ * `~0.1.0`, `0.1.0-alpha.19`, `>=0.1.0-alpha.0 <0.2.0`. Null for
+ * `workspace:*`, tags and URLs.
+ *
+ * @param {string} spec
+ */
+export function coerce(spec) {
+  const match = /(?:^|[\s^~>=<v])(\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?)/.exec(
+    ` ${String(spec).trim()}`,
+  );
+  if (!match) return null;
+  const parsed = parse(match[1]);
+  return parsed ? format(parsed) : null;
+}
+
+/** @param {string} a @param {string} b */
+function compareIdentifiers(a, b) {
+  const na = /^\d+$/.test(a);
+  const nb = /^\d+$/.test(b);
+  if (na && nb) return Number(a) - Number(b);
+  if (na) return -1;
+  if (nb) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Semver precedence. A version with a prerelease sorts before the same
+ * version without one.
+ *
+ * @param {string} a
+ * @param {string} b
+ */
+export function compare(a, b) {
+  const va = parse(a);
+  const vb = parse(b);
+  if (!va || !vb) throw new Error(`Not a version: ${!va ? a : b}`);
+  for (const key of /** @type {const} */ (["major", "minor", "patch"])) {
+    if (va[key] !== vb[key]) return va[key] - vb[key];
+  }
+  if (va.pre.length === 0 || vb.pre.length === 0) {
+    return vb.pre.length - va.pre.length;
+  }
+  for (let i = 0; i < Math.max(va.pre.length, vb.pre.length); i++) {
+    const x = va.pre[i];
+    const y = vb.pre[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const c = compareIdentifiers(x, y);
+    if (c !== 0) return c;
+  }
+  return 0;
+}
+
+/**
+ * The version after `version` for a release that carries a breaking change:
+ * the next prerelease number while in prerelease, else the next minor (pre-1.0
+ * a breaking change bumps the minor).
+ *
+ * @param {string} version
+ */
+export function nextBreaking(version) {
+  const v = parse(version);
+  if (!v) throw new Error(`Not a version: ${version}`);
+  if (v.pre.length > 0) {
+    const last = v.pre[v.pre.length - 1];
+    const pre = /^\d+$/.test(last)
+      ? [...v.pre.slice(0, -1), String(Number(last) + 1)]
+      : [...v.pre, "1"];
+    return format({ ...v, pre });
+  }
+  if (v.major === 0) return format({ major: 0, minor: v.minor + 1, patch: 0, pre: [] });
+  return format({ major: v.major + 1, minor: 0, patch: 0, pre: [] });
+}
+
+/**
+ * @typedef {{version: string, inclusive: boolean, text?: string}} Bound
+ * `text` is the comparator as written, kept when the bound survives.
+ */
+
+/**
+ * A partial version (`19`, `19.x`, `19.2.*`) as its first admitted version
+ * and the version its x-range stops before. Null for anything else.
+ *
+ * @param {string} input
+ */
+function partial(input) {
+  const m =
+    /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+      input,
+    );
+  if (!m) return null;
+  const wild = (/** @type {string | undefined} */ s) => s == null || /^[xX*]$/.test(s);
+  if (wild(m[1])) return { min: null, end: null, full: false, parts: 0 };
+  const major = Number(m[1]);
+  if (wild(m[2]))
+    return { min: `${major}.0.0`, end: `${major + 1}.0.0`, full: false, parts: 1 };
+  const minor = Number(m[2]);
+  if (wild(m[3]))
+    return {
+      min: `${major}.${minor}.0`,
+      end: `${major}.${minor + 1}.0`,
+      full: false,
+      parts: 2,
+    };
+  const version = `${major}.${minor}.${Number(m[3])}${m[4] ? `-${m[4]}` : ""}`;
+  return { min: version, end: null, full: true, parts: 3 };
+}
+
+/**
+ * One `||` alternative as a lower and an upper bound; null when it is not a
+ * range this reads (a tag, a URL).
+ *
+ * @param {string} alternative
+ * @returns {{lower: Bound | null, upper: Bound | null, hyphen?: string} | null}
+ */
+function bounds(alternative) {
+  const text = alternative.trim();
+  if (text === "") return { lower: null, upper: null };
+  const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(text);
+  if (hyphen) {
+    const from = partial(hyphen[1]);
+    const to = partial(hyphen[2]);
+    if (!from || !to) return null;
+    return {
+      lower: from.min ? { version: from.min, inclusive: true } : null,
+      upper: to.full
+        ? { version: /** @type {string} */ (to.min), inclusive: true }
+        : to.end
+          ? { version: to.end, inclusive: false }
+          : null,
+      hyphen: hyphen[2],
+    };
+  }
+  /** @type {Bound | null} */
+  let lower = null;
+  /** @type {Bound | null} */
+  let upper = null;
+  /** @param {Bound} b */
+  const raise = (b) => {
+    if (!lower || compare(b.version, lower.version) > 0) lower = b;
+  };
+  /** @param {Bound} b */
+  const cap = (b) => {
+    const c = upper ? compare(b.version, upper.version) : -1;
+    if (c < 0 || (c === 0 && !b.inclusive)) upper = b;
+  };
+  for (const token of text.replace(/(<=|>=|[<>=^~])\s+/g, "$1").split(/\s+/)) {
+    const m = /^(<=|>=|<|>|=|\^|~)?(.*)$/.exec(token);
+    const op = m?.[1] ?? "";
+    const v = partial(m?.[2] ?? "");
+    if (!v) return null;
+    if (!v.min) {
+      // `*`, `x`, `>=*`: no bound; `<*` admits nothing.
+      if (op === "<" || op === ">")
+        return { lower: null, upper: { version: "0.0.0", inclusive: false } };
+      continue;
+    }
+    const at = /** @type {string} */ (v.min);
+    if (op === "^" || op === "~") {
+      const p = /** @type {{major: number, minor: number, patch: number}} */ (
+        parse(at)
+      );
+      raise({ version: at, inclusive: true });
+      const end =
+        op === "~"
+          ? v.parts >= 2
+            ? `${p.major}.${p.minor + 1}.0`
+            : `${p.major + 1}.0.0`
+          : p.major > 0 || v.parts === 1
+            ? `${p.major + 1}.0.0`
+            : p.minor > 0 || v.parts === 2
+              ? `0.${p.minor + 1}.0`
+              : `0.0.${p.patch + 1}`;
+      cap({ version: end, inclusive: false });
+    } else if (op === ">=") raise({ version: at, inclusive: true, text: token });
+    else if (op === ">")
+      raise(
+        v.full
+          ? { version: at, inclusive: false, text: token }
+          : { version: /** @type {string} */ (v.end), inclusive: true, text: token },
+      );
+    else if (op === "<") cap({ version: at, inclusive: false, text: token });
+    else if (op === "<=")
+      cap(
+        v.full
+          ? { version: at, inclusive: true, text: token }
+          : { version: /** @type {string} */ (v.end), inclusive: false, text: token },
+      );
+    else {
+      raise({ version: at, inclusive: true });
+      cap(
+        v.full
+          ? { version: at, inclusive: true }
+          : { version: /** @type {string} */ (v.end), inclusive: false },
+      );
+    }
+  }
+  return { lower, upper };
+}
+
+/**
+ * `range` narrowed to the versions at or above `floor`, alternative by
+ * alternative: `>=18 <21 || ^22` at 19.2.0 is `>=19.2.0 <21 || ^22`. An
+ * alternative already above the floor keeps its text; one wholly below it is
+ * dropped. Null when nothing is left; `range` itself when it is not a range
+ * this reads.
+ *
+ * @param {string} range
+ * @param {string} floor a full version
+ * @returns {string | null}
+ */
+export function narrowToFloor(range, floor) {
+  const f = parse(floor);
+  if (!f) throw new Error(`Not a version: ${floor}`);
+  const alternatives = range.split("||").map((a) => a.trim());
+  const parsed = alternatives.map(bounds);
+  if (parsed.some((b) => b == null)) return range;
+  /** @type {string[]} */
+  const kept = [];
+  for (const [i, b] of /** @type {NonNullable<ReturnType<typeof bounds>>[]} */ (
+    parsed
+  ).entries()) {
+    const { lower, upper } = b;
+    if (lower && compare(lower.version, floor) >= 0) {
+      kept.push(alternatives[i]);
+      continue;
+    }
+    if (upper) {
+      const c = compare(upper.version, floor);
+      if (c < 0 || (c === 0 && !upper.inclusive)) continue;
+    }
+    let next;
+    if (!upper) next = `>=${floor}`;
+    else if (b.hyphen != null) next = `${floor} - ${b.hyphen}`;
+    else if (!upper.inclusive && upper.version === `${f.major + 1}.0.0` && f.major > 0)
+      next = `^${floor}`;
+    else if (upper.inclusive && upper.version === floor) next = floor;
+    else
+      next = `>=${floor} ${upper.text ?? `${upper.inclusive ? "<=" : "<"}${upper.version}`}`;
+    kept.push(next);
+  }
+  const unique = [...new Set(kept)];
+  if (unique.length === 0) return null;
+  return unique.length === alternatives.length &&
+    unique.every((a, i) => a === alternatives[i])
+    ? range
+    : unique.join(" || ");
+}

package/cli/shadow.mjs

@@ -0,0 +1,161 @@
+/**
+ * Let Astryx's lookup commands find @astryxdesign/core in a project that only
+ * depends on @lablup/ui-common.
+ *
+ * `astryx component`, `search`, `docs`, `build` and friends locate core by
+ * walking up from the working directory for `node_modules/@astryxdesign/core`.
+ * Under pnpm's isolated layout a ui-common consumer has no such directory:
+ * core is ui-common's dependency, not the project's. So, for read-only
+ * commands only, the CLI runs in a throwaway "shadow" of the project: its
+ * package.json, config and lockfile, and a node_modules made of symlinks to
+ * the project's own packages plus the Astryx packages ui-common pins. The
+ * project's integrations (ui-common's included) load exactly as they would in
+ * place. Paths in the output are mapped back to the project.
+ *
+ * Commands that write files (`init`, `swizzle`, `template <name> <path>`,
+ * `theme add`, …) never run in a shadow.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { dependencyDir, findProjectDir } from "./paths.mjs";
+
+/** Astryx commands that only read. */
+const READ_ONLY = new Set([
+  "component",
+  "search",
+  "docs",
+  "build",
+  "hook",
+  "discover",
+  "blog",
+  "layout",
+  "template",
+]);
+
+const ASTRYX_PACKAGES = [
+  "@astryxdesign/core",
+  "@astryxdesign/theme-neutral",
+  "@astryxdesign/lab",
+];
+
+const PROJECT_FILES = [
+  "package.json",
+  "astryx.config.ts",
+  "astryx.config.mts",
+  "astryx.config.js",
+  "astryx.config.mjs",
+  "astryx.config.cjs",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "package-lock.json",
+  "bun.lock",
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".claude",
+  ".cursorrules",
+];
+
+/**
+ * Whether the Astryx CLI finds core from `cwd` (its own findCoreDir walk:
+ * five levels of `packages/core` or `node_modules/@astryxdesign/core`).
+ *
+ * @param {string} cwd
+ */
+export function coreReachableFrom(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(join(dir, "packages", "core"))) return true;
+    if (existsSync(join(dir, "node_modules", "@astryxdesign", "core"))) return true;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+/**
+ * Whether this command should run in a shadow of the project.
+ *
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+export function needsShadow(args, cwd) {
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  const command = positionals[0];
+  if (!command || !READ_ONLY.has(command)) return false;
+  // `template <name> <path>` and `--cdn` write files.
+  if (
+    command === "template" &&
+    (positionals.length > 2 || args.some((a) => a.startsWith("--cdn")))
+  ) {
+    return false;
+  }
+  if (!dependencyDir("@astryxdesign/core")) return false;
+  return !coreReachableFrom(cwd);
+}
+
+/** @param {string} target @param {string} link */
+function link(target, link) {
+  symlinkSync(target, link, process.platform === "win32" ? "junction" : undefined);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{dir: string, projectDir: string, cleanup: () => void}}
+ */
+export function createShadow(cwd) {
+  const projectDir = findProjectDir(cwd) ?? cwd;
+  const dir = mkdtempSync(join(tmpdir(), "ui-common-astryx-"));
+  for (const file of PROJECT_FILES) {
+    const source = join(projectDir, file);
+    if (existsSync(source)) link(source, join(dir, file));
+  }
+
+  const modules = join(dir, "node_modules");
+  mkdirSync(modules);
+  // The project's installed packages, from the nearest node_modules.
+  let search = projectDir;
+  for (;;) {
+    const nm = join(search, "node_modules");
+    if (existsSync(nm)) {
+      for (const entry of readdirSync(nm)) {
+        if (entry.startsWith(".")) continue;
+        if (entry.startsWith("@")) {
+          mkdirSync(join(modules, entry), { recursive: true });
+          for (const scoped of readdirSync(join(nm, entry))) {
+            link(join(nm, entry, scoped), join(modules, entry, scoped));
+          }
+        } else {
+          link(join(nm, entry), join(modules, entry));
+        }
+      }
+      break;
+    }
+    const parent = dirname(search);
+    if (parent === search) break;
+    search = parent;
+  }
+  // The Astryx packages ui-common pins, where the project has none.
+  for (const name of ASTRYX_PACKAGES) {
+    const target = join(modules, ...name.split("/"));
+    const source = dependencyDir(name);
+    if (!source || existsSync(target)) continue;
+    mkdirSync(dirname(target), { recursive: true });
+    link(source, target);
+  }
+
+  return {
+    dir,
+    projectDir,
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}