@hirobius/design-system 0.21.0 → 0.22.0

package/codemods/lib/scan.mjs

@@ -0,0 +1,323 @@
+/**
+ * scan — read a consumer's code once and answer a ledger step's `detect`
+ * (upgrade/schema.json, $defs.detect) against it (hds#452).
+ *
+ * Node builtins only: this runs on consumer machines from the published
+ * package. Each detector reads the files it can mean something in:
+ *
+ *   imports, jsx, bareImports   code (.ts .tsx .js .jsx .mjs .cjs .mts .cts .mdx)
+ *   classes                     code (className / class attributes), CSS
+ *                               selectors and @apply, HTML class attributes
+ *   cssVars, cssVarWrites       code, CSS and HTML
+ *   regex                       code, CSS and HTML
+ *
+ * Plain Markdown is not read: a README that mentions a name is not a use.
+ */
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { HDS_PACKAGE as HDS } from './installed-version.mjs';
+
+/** Directories never read: dependencies, VCS data and build output. */
+export const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.vercel',
+  '.turbo',
+  '.svelte-kit',
+  'coverage',
+  'storybook-static',
+]);
+
+const CODE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.mdx']);
+const STYLE = new Set(['.css', '.scss']);
+const MARKUP = new Set(['.html']);
+
+/** Files larger than this are generated or vendored, not code a person wrote. */
+export const MAX_BYTES = 1_000_000;
+
+const extOf = (name) => {
+  const dot = name.lastIndexOf('.');
+  return dot === -1 ? '' : name.slice(dot).toLowerCase();
+};
+
+/**
+ * Every file under `root` a detector reads, with its text.
+ * @param {string} root
+ * @param {{ skip?: string[], oversized?: { rel: string, abs: string }[] }} [options]
+ *   skip: absolute directories not to enter (nested importers); oversized:
+ *   collects the files of a kind a detector reads that are over MAX_BYTES,
+ *   so the caller can say they were not read instead of passing them over.
+ * @returns {{ rel: string, ext: string, kind: 'code'|'style'|'markup', text: string }[]}
+ */
+export function collectFiles(root, { skip = [], oversized = null } = {}) {
+  const skipped = new Set(skip.map((dir) => resolve(dir)));
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name) && !skipped.has(full)) walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = extOf(entry.name);
+      const kind = CODE.has(ext)
+        ? 'code'
+        : STYLE.has(ext)
+          ? 'style'
+          : MARKUP.has(ext)
+            ? 'markup'
+            : null;
+      if (!kind) continue;
+      try {
+        const rel = relative(root, full).split(sep).join('/');
+        if (statSync(full).size > MAX_BYTES) {
+          oversized?.push({ rel, abs: full });
+          continue;
+        }
+        out.push({
+          rel,
+          ext,
+          kind,
+          text: readFileSync(full, 'utf8'),
+        });
+      } catch {
+        // unreadable: not ours to report
+      }
+    }
+  };
+  walk(resolve(root));
+  return out;
+}
+
+/**
+ * Whether a file holds `needle`, read in chunks so a file of any size costs
+ * one buffer (for the files collectFiles leaves out as too big). An
+ * unreadable file counts as holding it: the caller cannot rule it out.
+ */
+export function fileMentions(file, needle) {
+  const CHUNK = 1 << 20;
+  const buf = Buffer.alloc(CHUNK);
+  const target = Buffer.from(needle);
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    let carry = Buffer.alloc(0);
+    for (;;) {
+      const n = readSync(fd, buf, 0, CHUNK, null);
+      if (n === 0) return false;
+      const chunk = Buffer.concat([carry, buf.subarray(0, n)]);
+      if (chunk.includes(target)) return true;
+      carry = chunk.subarray(Math.max(0, chunk.length - (target.length - 1)));
+    }
+  } catch {
+    return true;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+const stripComments = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+
+const NAMED =
+  /\b(?:import|export)\s+(?:type\s+)?(?:[\w$]+\s*,\s*)?\{([^}]*)\}\s*from\s*(['"])([^'"\n]+)\2/g;
+
+const DESTRUCTURED =
+  /\b(?:const|let|var)\s*\{([^}]*)\}\s*=\s*(?:await\s+)?(?:require|import)\s*\(\s*(['"])([^'"\n]+)\2\s*\)/g;
+
+/**
+ * Named imports and re-exports in a file: `{ from, name, local }`. Also the
+ * names a `const { a, b: c } = require(...)` or `= await import(...)`
+ * destructures, which bind the same exports.
+ */
+export function namedImports(text) {
+  const out = [];
+  for (const m of text.matchAll(DESTRUCTURED)) {
+    for (const raw of stripComments(m[1]).split(',')) {
+      const spec = raw.trim().replace(/\s*=[\s\S]*$/, '');
+      if (!spec || spec.startsWith('...')) continue;
+      const [name, local = name] = spec.split(':').map((s) => s.trim());
+      if (/^[\w$]+$/.test(name) && /^[\w$]+$/.test(local)) out.push({ from: m[3], name, local });
+    }
+  }
+  for (const m of text.matchAll(NAMED)) {
+    for (const raw of stripComments(m[1]).split(',')) {
+      const spec = raw.trim().replace(/^type\s+/, '');
+      if (!spec) continue;
+      const [name, local = name] = spec.split(/\s+as\s+/).map((s) => s.trim());
+      out.push({ from: m[3], name, local });
+    }
+  }
+  return out;
+}
+
+const NAMESPACE_FORMS = [
+  /\bimport\s+(?:type\s+)?(?:[\w$]+\s*,\s*)?\*\s*as\s+([\w$]+)\s+from\s*(['"])([^'"\n]+)\2/g,
+  /\bimport\s+(?:type\s+)?([\w$]+)\s*(?:,\s*\{[^}]*\}\s*)?from\s*(['"])([^'"\n]+)\2/g,
+  /\b(?:const|let|var)\s+([\w$]+)\s*=\s*(?:await\s+)?(?:require|import)\s*\(\s*(['"])([^'"\n]+)\2\s*\)/g,
+];
+
+/**
+ * Namespace bindings in a file: `import * as X from`, `import X from` and
+ * `const X = require(...)` bind the whole module, so `X.Name` is the export
+ * Name. `{ from, local }` for each.
+ */
+export function namespaceImports(text) {
+  const out = [];
+  for (const re of NAMESPACE_FORMS) {
+    for (const m of text.matchAll(re)) out.push({ from: m[3], local: m[1] });
+  }
+  return out;
+}
+
+const SPECIFIERS = [
+  /\bfrom\s*(['"])([^'"\n]+)\1/g,
+  /\bimport\s*(['"])([^'"\n]+)\1/g,
+  /\b(?:require|import)\s*\(\s*(['"])([^'"\n]+)\1\s*\)/g,
+];
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?(['"])([^'"\n]+)\1/g;
+
+/** Every module specifier a file imports or requires. */
+function specifiers(file) {
+  const patterns = file.kind === 'style' ? [CSS_IMPORT] : file.kind === 'code' ? SPECIFIERS : [];
+  return patterns.flatMap((re) => [...file.text.matchAll(re)].map((m) => m[2]));
+}
+
+const CLASS_ATTR =
+  /\bclass(?:Name)?\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`))/g;
+
+/** The class tokens a file's class / className attributes name. */
+function attrClasses(text) {
+  const out = new Set();
+  for (const m of text.matchAll(CLASS_ATTR)) {
+    const value = m.slice(1).find((v) => v !== undefined) ?? '';
+    for (const token of value.split(/\s+/)) if (token) out.add(token);
+  }
+  return out;
+}
+
+/** A class name as a CSS selector writes it: `sm:text-4xl` → `sm\:text-4xl`. */
+const cssEscape = (name) => name.replace(/[^\w-]/g, (ch) => `\\${ch}`);
+
+function usesClass(file, name) {
+  if (file.kind === 'style') {
+    const selector = new RegExp(`\\.${escapeRe(cssEscape(name))}(?![\\w-]|\\\\)`);
+    if (selector.test(file.text)) return true;
+    for (const m of file.text.matchAll(/@apply\s+([^;}]+)/g)) {
+      if (m[1].split(/\s+/).includes(name)) return true;
+    }
+    return false;
+  }
+  return attrClasses(file.text).has(name);
+}
+
+/** The local name each HDS export is bound to in a file (`Card as Panel` → Card: [Panel]). */
+function hdsBindings(file) {
+  const out = new Map();
+  for (const { from, name, local } of namedImports(file.text)) {
+    if (from !== HDS && !from.startsWith(`${HDS}/`)) continue;
+    out.set(name, [...(out.get(name) ?? []), local]);
+  }
+  return out;
+}
+
+/** The local names bound to the whole HDS module (or a subpath) in a file. */
+function hdsNamespaces(file) {
+  return namespaceImports(file.text)
+    .filter(({ from }) => from === HDS || from.startsWith(`${HDS}/`))
+    .map(({ local }) => local);
+}
+
+function usesJsx(file, tag) {
+  const [head, ...rest] = tag.split('.');
+  const locals = hdsBindings(file).get(head) ?? [];
+  const tail = rest.map((part) => `\\.${escapeRe(part)}`).join('');
+  if (locals.some((local) => new RegExp(`<${escapeRe(local)}${tail}(?=[\\s/>])`).test(file.text))) {
+    return true;
+  }
+  // `<X.StatusDot` where X is a namespace binding of the package.
+  return hdsNamespaces(file).some((ns) =>
+    new RegExp(`<${escapeRe(ns)}\\.${escapeRe(tag)}(?=[\\s/>])`).test(file.text),
+  );
+}
+
+/** Does the file reach one of `names` of `from` as `X.Name` on a namespace binding? */
+function usesNamespaceMember(file, from, names) {
+  return namespaceImports(file.text)
+    .filter((ns) => ns.from === from)
+    .some((ns) =>
+      names.some((name) =>
+        new RegExp(`(?<![\\w$.])${escapeRe(ns.local)}\\s*\\.\\s*${escapeRe(name)}(?![\\w$])`).test(
+          file.text,
+        ),
+      ),
+    );
+}
+
+const compiled = new Map();
+const regexOf = (source) => {
+  if (!compiled.has(source)) compiled.set(source, new RegExp(source));
+  return compiled.get(source);
+};
+
+/** Does one file hold a use the detect describes? Any key matching is a use. */
+function fileMatches(detect, file) {
+  const code = file.kind === 'code';
+  if (code && detect.imports) {
+    const found = namedImports(file.text);
+    const hit = detect.imports.some((want) =>
+      found.some((f) => f.from === want.from && want.names.includes(f.name)),
+    );
+    if (hit) return true;
+    if (detect.imports.some((want) => usesNamespaceMember(file, want.from, want.names))) {
+      return true;
+    }
+  }
+  if (code && detect.jsx?.some((tag) => usesJsx(file, tag))) return true;
+  if (detect.bareImports) {
+    const specs = specifiers(file);
+    const hit = detect.bareImports.some((pkg) =>
+      specs.some((s) => s === pkg || s.startsWith(`${pkg}/`)),
+    );
+    if (hit) return true;
+  }
+  if (
+    detect.cssVars?.some((v) => new RegExp(`var\\(\\s*${escapeRe(v)}(?![\\w-])`).test(file.text))
+  ) {
+    return true;
+  }
+  if (
+    detect.cssVarWrites?.some((v) =>
+      new RegExp(`(?<![\\w-])${escapeRe(v)}['"]?\\s*:`).test(file.text),
+    )
+  ) {
+    return true;
+  }
+  if (detect.classes?.some((name) => usesClass(file, name))) return true;
+  if (detect.regex?.some((source) => regexOf(source).test(file.text))) return true;
+  return false;
+}
+
+/**
+ * The files (relative, sorted) that hold a use `detect` describes.
+ * @param {Record<string, any>} detect a ledger step's detect (or done)
+ * @param {ReturnType<typeof collectFiles>} files
+ * @returns {string[]}
+ */
+export function matchDetect(detect, files) {
+  if (!detect) return [];
+  return files
+    .filter((file) => fileMatches(detect, file))
+    .map((file) => file.rel)
+    .sort();
+}

package/codemods/lib/semver.mjs

@@ -0,0 +1,57 @@
+/**
+ * semver — the little of semver the upgrade command needs (hds#452), Node
+ * builtins only. compareVersions is installed-version.mjs's, so the lockfile
+ * readers and the command order versions the same way.
+ */
+import { compareVersions } from './installed-version.mjs';
+
+export { compareVersions };
+
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+export const isVersion = (value) => typeof value === 'string' && VERSION.test(value);
+
+/** One comparator: an optional operator and a full or partial version (`^0.16`, `0.16.0`). */
+const SIMPLE = /^(\^|~|>=|=)?\s*v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?(-[0-9A-Za-z.-]+)?$/;
+
+/**
+ * The range a package.json declares, moved to `target` with its operator kept:
+ * `^0.16.0` → `^0.21.0`, `~0.16.2` → `~0.21.0`, `0.16.0` → `0.21.0`,
+ * `>=0.16.0` → `>=0.21.0`; an x-range or partial version keeps its wildcard
+ * (`0.16.x` → `0.21.x`, `0.x` stays); an `npm:` alias keeps its prefix. Null for a range
+ * it cannot move safely (`workspace:*`, `latest`, a compound range, a URL).
+ * @param {string} range
+ * @param {string} target
+ * @returns {string|null}
+ */
+export function bumpRange(range, target) {
+  const alias = /^(npm:(?:@[^@/\s]+\/)?[^@\s]+@)(.*)$/.exec(range);
+  if (alias) {
+    const inner = bumpRange(alias[2], target);
+    return inner === null ? null : `${alias[1]}${inner}`;
+  }
+  const m = SIMPLE.exec(range.trim());
+  if (!m) return null;
+  const [, op = '', maj, min, pat, pre] = m;
+  const wild = (part) => part === undefined || part === 'x' || part === '*';
+  if (op === '' && (wild(min) || wild(pat))) {
+    // An x-range or a partial version (`0.16.x`, `0.x`, `0.16`) stays a
+    // wildcard of the same shape, so the consumer keeps getting patches.
+    if (pre) return null;
+    const [tMaj, tMin] = target.split('.');
+    const parts = [tMaj];
+    if (min !== undefined) parts.push(wild(min) ? min : tMin);
+    // Here a patch part is a wildcard, or follows one (`0.x.x`): keep it.
+    if (pat !== undefined) parts.push(pat);
+    return parts.join('.');
+  }
+  if (op === '=' && (wild(min) || wild(pat))) return null;
+  return `${op}${target}`;
+}
+
+/**
+ * Whether `range` already names `target` (bumpRange would leave it as it is).
+ * @param {string} range
+ * @param {string} target
+ */
+export const rangeIsAt = (range, target) => bumpRange(range, target) === range;

package/codemods/not-found-pattern.mjs

@@ -61,9 +61,9 @@ export function transformSource(source) {
   return foldComponent(source, RULE);
 }
 
-/** Scan a directory. Writes only when `write` is true. */
-export function runCodemod({ root, write = false }) {
-  return runFold({ root, write, rule: RULE });
+/** Scan a directory. Writes only when `write` is true; `skip` lists directories not to enter. */
+export function runCodemod({ root, write = false, skip = [] }) {
+  return runFold({ root, write, rule: RULE, skip });
 }
 
 if (isEntry(import.meta.url)) {

package/codemods/patterns-subpath.mjs

@@ -41,7 +41,8 @@
  * ("removed in 0.20.0, use Button iconOnly"). NotFoundPattern and TileGrid
  * (hds#395) have codemods of their own: hds-not-found-pattern and hds-tile-grid.
  */
-import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { writeFileAtomic } from './lib/atomic-write.mjs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findUnrewritable as findHidden, maskSource } from './unrewritable.mjs';
@@ -312,30 +313,45 @@ export function transformSource(source, names) {
   return { source: out, changed: out !== source, sites, moved, edits };
 }
 
-function* walk(dir) {
-  for (const entry of readdirSync(dir)) {
-    if (SKIP_DIRS.has(entry)) continue;
-    const full = join(dir, entry);
-    const st = statSync(full);
-    if (st.isDirectory()) yield* walk(full);
-    else if (EXTS.has(full.slice(full.lastIndexOf('.')))) yield full;
+/** `skip`: absolute directories not to enter (the upgrade command's nested importers). */
+function* walk(dir, skip = new Set()) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // an unreadable directory has nothing to rewrite
+  }
+  // Symlinks are skipped, never followed: a dangling one cannot be read and a
+  // looping one never ends.
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!skip.has(full)) yield* walk(full, skip);
+    } else if (entry.isFile() && EXTS.has(full.slice(full.lastIndexOf('.')))) yield full;
   }
 }
 
-/** Scan a directory. Writes only when `write` is true. */
+/** Scan a directory. Writes only when `write` is true; `skip` lists directories not to enter. */
 export function runCodemod({
   root,
   write = false,
   names = loadPatternNames(),
   removed = loadRemovedNames(),
   replacements = loadReplacements(),
+  skip = [],
 }) {
   const files = [];
   const manual = [];
   const moved = new Set();
   let sites = 0;
-  for (const file of walk(root)) {
-    const src = readFileSync(file, 'utf8');
+  for (const file of walk(root, new Set(skip.map((d) => resolve(d))))) {
+    let src;
+    try {
+      src = readFileSync(file, 'utf8');
+    } catch {
+      continue; // unreadable: nothing to rewrite
+    }
     if (!src.includes(ROOT_PKG)) continue;
     for (const stmt of findUnrewritable(src, names))
       manual.push({ file: relative(root, file), stmt });
@@ -346,7 +362,7 @@ export function runCodemod({
     files.push({ file: relative(root, file), sites: r.sites, moved: r.moved, edits: r.edits });
     r.moved.forEach((n) => moved.add(n));
     sites += r.sites;
-    if (write) writeFileSync(file, r.source);
+    if (write) writeFileAtomic(file, r.source);
   }
   return { files, sites, manual, names: [...moved].sort() };
 }

package/codemods/registry.mjs

@@ -0,0 +1,67 @@
+/**
+ * registry — the codemods this package ships, behind one interface (hds#452).
+ *
+ * A ledger step names its codemod by bin (`auto.codemod`, such as
+ * hds-patterns-subpath). The upgrade command looks it up here and runs it
+ * in-process, so it can skip nested workspace importers and read back which
+ * files changed; `child: true` runs the bin's file as a child process with
+ * --root/--check/--dry-run instead, exactly as a person would.
+ *
+ *   await runCodemod('hds-prefix', { root, write: true, skip: [nestedDir] })
+ *   → { files: ['src/a.tsx'], sites: 1, manual: [{ file, stmt, removed? }] }
+ *
+ *   await runCodemod('hds-prefix', { root, check: true, child: true })
+ *   → { status: 1, output: '…' }
+ *
+ * Node builtins only. Each entry's file is the one package.json#bin points at
+ * (a test holds them equal).
+ */
+import { spawnSync } from 'node:child_process';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** bin name → the file in codemods/ that implements it. */
+export const CODEMODS = Object.freeze({
+  'hds-patterns-subpath': { file: 'patterns-subpath.mjs' },
+  'hds-prefix': { file: 'hds-prefix.mjs' },
+  'hds-not-found-pattern': { file: 'not-found-pattern.mjs' },
+  'hds-tile-grid': { file: 'tile-grid.mjs' },
+});
+
+export const hasCodemod = (name) => Object.hasOwn(CODEMODS, name);
+
+const toPosix = (p) => p.split(sep).join('/');
+
+/**
+ * Run one codemod over `root`.
+ * @param {string} name a bin name from CODEMODS
+ * @param {{ root: string, write?: boolean, skip?: string[], child?: boolean, check?: boolean, dryRun?: boolean }} options
+ *   In-process: `write` writes the edits, `skip` lists absolute directories not
+ *   to enter. As a child: `check` / `dryRun` pass the flags of the same name.
+ */
+export async function runCodemod(name, options) {
+  if (!hasCodemod(name)) {
+    throw new Error(
+      `Unknown codemod ${name}: this package ships ${Object.keys(CODEMODS).join(', ')}`,
+    );
+  }
+  const file = join(HERE, CODEMODS[name].file);
+  if (options.child) {
+    const args = [file, '--root', options.root];
+    if (options.check) args.push('--check');
+    if (options.dryRun) args.push('--dry-run');
+    const res = spawnSync(process.execPath, args, { encoding: 'utf8' });
+    return { status: res.status, output: `${res.stdout ?? ''}${res.stderr ?? ''}` };
+  }
+  const mod = await import(pathToFileURL(file).href);
+  const res = mod.runCodemod({
+    root: options.root,
+    write: options.write === true,
+    skip: options.skip ?? [],
+  });
+  const files = res.files.map((f) => toPosix(f.file));
+  const manual = res.manual.map((m) => ({ ...m, file: toPosix(m.file) }));
+  return { files, sites: res.sites, manual };
+}

package/codemods/tile-grid.mjs

@@ -273,9 +273,9 @@ export function transformSource(source) {
   return foldComponent(source, RULE);
 }
 
-/** Scan a directory. Writes only when `write` is true. */
-export function runCodemod({ root, write = false }) {
-  return runFold({ root, write, rule: RULE });
+/** Scan a directory. Writes only when `write` is true; `skip` lists directories not to enter. */
+export function runCodemod({ root, write = false, skip = [] }) {
+  return runFold({ root, write, rule: RULE, skip });
 }
 
 if (isEntry(import.meta.url)) {