@hirobius/design-system 0.17.0 → 0.18.0

package/README.md

@@ -23,6 +23,22 @@ pnpm add @hirobius/design-system
 
 The counts are generated from source by `pnpm readme:counts`, which `pnpm tokens` also runs. `scripts/__tests__/front-door.test.mjs` fails if this README claims more than the source has.
 
+## In use
+
+<!-- auto:start:consumer-usage -->
+
+The Ops dashboard (`hirobius/ops`) is the only verified component-level consumer: **35** of its source files import from `@hirobius/design-system`, using **25** distinct components. The two screenshots below are Ops pages rendered from its `main` (measured at commit `01fce2f`).
+
+Other consumers: the split into product apps and token-level sites is not yet confirmed, so it is not stated here.
+
+[![Ops library page](docs/images/ops-library.png)](docs/images/ops-library.png)
+
+[![Ops fleet audit page](docs/images/ops-fleet-audit.png)](docs/images/ops-fleet-audit.png)
+
+<!-- auto:end:consumer-usage -->
+
+The numbers come from `pnpm consumer:usage --root <ops checkout>`, which measures that checkout and records its commit in `docs/data/consumer-usage.json`; without a root it reuses the committed snapshot. `scripts/__tests__/consumer-usage.test.mjs` fails if this section drifts from that snapshot. The product-app and token-level-site split is a declared figure in that file and stays out of this section until `consumersConfirmed` there is set to true.
+
 ## Using the published package
 
 Installing HDS in another project? It ships to the **public npm registry** as

package/codemods/patterns-subpath.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * patterns-subpath codemod (hds#316, follows hds#254)
+ *
+ * Rewrites `import { Page } from '@hirobius/design-system'` to
+ * `import { Page } from '@hirobius/design-system/patterns'` for every
+ * pattern-tier component whose root re-export is deprecated. Other named
+ * imports stay on the root. Aliases, `type` modifiers and multi-line layout
+ * are preserved; an existing `/patterns` import of the same kind is extended
+ * instead of duplicated.
+ *
+ *   node codemods/patterns-subpath.mjs [--root <dir>] [--check] [--dry-run]
+ *
+ *   --root <dir>  directory to scan (default: current directory)
+ *   --check       write nothing; exit 1 when a rewrite is needed or a root namespace
+ *                 import (`import * as X`, `export *`) needs a manual look
+ *   --dry-run     write nothing; print each import line before (-) and after (+), exit 0
+ *
+ * The name list is codemods/patterns-subpath.names.json, generated from
+ * src/index.ts by `pnpm codemod:names`.
+ */
+import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT_PKG = '@hirobius/design-system';
+const SUBPATH = `${ROOT_PKG}/patterns`;
+const HERE = dirname(fileURLToPath(import.meta.url));
+const EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.git',
+  '.next',
+  '.vercel',
+  'coverage',
+  'storybook-static',
+]);
+
+export function loadPatternNames() {
+  const { names } = JSON.parse(readFileSync(join(HERE, 'patterns-subpath.names.json'), 'utf8'));
+  return new Set(names);
+}
+
+const esc = (pkg) => pkg.replace(/[/@]/g, '\\$&');
+// indent, import|export, type?, default?, { body }, quote, semicolon
+const namedRe = (pkg) =>
+  new RegExp(
+    `^([ \\t]*)(import|export)(\\s+type)?\\s*(?:([\\w$]+)\\s*,\\s*)?\\{([^}]*)\\}\\s*from\\s*(['"])${esc(pkg)}\\6(;?)`,
+    'gm',
+  );
+// `import * as X`, `import D, * as X`, `export * from`, `export * as X from` on the root
+const namespaceRe = new RegExp(
+  `^[ \\t]*(?:import\\s+(?:[\\w$]+\\s*,\\s*)?\\*\\s*as\\s+[\\w$]+|export\\s+\\*(?:\\s*as\\s+[\\w$]+)?)\\s*from\\s*['"]${esc(ROOT_PKG)}['"]`,
+  'gm',
+);
+
+const specName = (spec) =>
+  spec
+    .replace(/^type\s+/, '')
+    .split(/\s+as\s+/)[0]
+    .trim();
+const splitSpecs = (body) =>
+  body
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+/** Namespace imports and star re-exports of the root: names are not visible, so no rewrite. */
+export function findUnrewritable(source) {
+  return [...source.matchAll(namespaceRe)].map((m) => m[0].trim());
+}
+
+/** Renders one import/export statement. */
+function render({ indent, kw, typeKw, def, list, pkg, multiline, quote, semi }) {
+  const head = `${indent}${kw}${typeKw ? ' type' : ''} `;
+  const tail = ` from ${quote}${pkg}${quote}${semi}`;
+  if (list.length === 0) return `${head}${def}${tail}`;
+  const d = def ? `${def}, ` : '';
+  if (multiline)
+    return `${head}${d}{\n${list.map((s) => `${indent}  ${s},`).join('\n')}\n${indent}}${tail}`;
+  return `${head}${d}{ ${list.join(', ')} }${tail}`;
+}
+
+/**
+ * Pure transform of one file's source.
+ * @returns {{ source: string, changed: boolean, sites: number, moved: string[],
+ *   edits: {before: string, after: string}[] }}
+ */
+export function transformSource(source, names) {
+  const moved = [];
+  const edits = [];
+  const isType = (m) => !!m[3];
+  const parse = (m) => ({
+    indent: m[1],
+    kw: m[2],
+    typeKw: m[3],
+    def: m[4],
+    body: m[5],
+    quote: m[6],
+    semi: m[7],
+  });
+
+  // An existing `import { … } from '/patterns'` of each kind absorbs moved names.
+  const targets = {};
+  for (const m of source.matchAll(namedRe(SUBPATH))) {
+    if (m[2] !== 'import' || m[4]) continue;
+    targets[isType(m) ? 'type' : 'value'] ??= { m, add: [] };
+  }
+
+  const replacements = [];
+  for (const m of source.matchAll(namedRe(ROOT_PKG))) {
+    const p = parse(m);
+    const specs = splitSpecs(p.body);
+    const go = specs.filter((s) => names.has(specName(s)));
+    if (go.length === 0) continue;
+    moved.push(...go.map(specName));
+    const keep = specs.filter((s) => !go.includes(s));
+    const multiline = p.body.includes('\n');
+    const lines = [];
+    if (keep.length > 0 || p.def)
+      lines.push(render({ ...p, list: keep, pkg: ROOT_PKG, multiline }));
+    const target = p.kw === 'import' && targets[p.typeKw ? 'type' : 'value'];
+    if (target) target.add.push(...go);
+    else lines.push(render({ ...p, def: undefined, list: go, pkg: SUBPATH, multiline }));
+    replacements.push({ start: m.index, end: m.index + m[0].length, before: m[0], lines });
+  }
+
+  if (replacements.length === 0) return { source, changed: false, sites: 0, moved: [], edits: [] };
+
+  const sites = replacements.length;
+  for (const { m, add } of Object.values(targets)) {
+    if (add.length === 0) continue;
+    const p = parse(m);
+    const have = splitSpecs(p.body);
+    const merged = [...have, ...add.filter((n) => !have.includes(n))];
+    replacements.push({
+      start: m.index,
+      end: m.index + m[0].length,
+      before: m[0],
+      lines: [
+        render({
+          ...p,
+          def: undefined,
+          list: merged,
+          pkg: SUBPATH,
+          multiline: p.body.includes('\n'),
+        }),
+      ],
+    });
+  }
+
+  let out = source;
+  for (const r of replacements.sort((x, y) => y.start - x.start)) {
+    const after = r.lines.join('\n');
+    // A statement folded entirely into an existing import leaves nothing behind, not a blank line.
+    const end = after === '' && out[r.end] === '\n' ? r.end + 1 : r.end;
+    out = out.slice(0, r.start) + after + out.slice(end);
+    edits.unshift({ before: r.before, after });
+  }
+  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;
+  }
+}
+
+/** Scan a directory. Writes only when `write` is true. */
+export function runCodemod({ root, write = false, names = loadPatternNames() }) {
+  const files = [];
+  const manual = [];
+  const moved = new Set();
+  let sites = 0;
+  for (const file of walk(root)) {
+    const src = readFileSync(file, 'utf8');
+    if (!src.includes(ROOT_PKG)) continue;
+    for (const stmt of findUnrewritable(src)) manual.push({ file: relative(root, file), stmt });
+    const r = transformSource(src, names);
+    if (!r.changed) continue;
+    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);
+  }
+  return { files, sites, manual, names: [...moved].sort() };
+}
+
+function main(argv) {
+  const args = { root: process.cwd(), check: false, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') args.root = resolve(argv[++i] ?? '');
+    else if (argv[i] === '--check') args.check = true;
+    else if (argv[i] === '--dry-run') args.dryRun = true;
+    else {
+      console.error(
+        `unknown argument: ${argv[i]}\nusage: patterns-subpath [--root <dir>] [--check] [--dry-run]`,
+      );
+      return 2;
+    }
+  }
+  const write = !args.check && !args.dryRun;
+  const res = runCodemod({ root: args.root, write });
+  const summary = `${res.files.length} files, ${res.sites} import sites, ${res.names.length} names (${res.names.join(', ') || 'none'})`;
+  const manualLines = res.manual.map(
+    (m) => `  ${m.file}: ${m.stmt} (namespace import: move pattern names to '${SUBPATH}' by hand)`,
+  );
+  if (args.check) {
+    if (res.sites > 0 || res.manual.length > 0) {
+      console.error(`patterns-subpath: rewrite needed: ${summary}`);
+      for (const f of res.files) console.error(`  ${f.file}: ${f.moved.join(', ')}`);
+      for (const l of manualLines) console.error(l);
+      return 1;
+    }
+    console.log('patterns-subpath: nothing to rewrite');
+    return 0;
+  }
+  console.log(`patterns-subpath: ${write ? 'rewrote' : 'would rewrite'} ${summary}`);
+  for (const f of res.files) {
+    console.log(`  ${f.file}: ${f.moved.join(', ')}`);
+    if (args.dryRun)
+      for (const e of f.edits) {
+        for (const l of e.before.split('\n')) console.log(`- ${l}`);
+        for (const l of e.after.split('\n')) console.log(`+ ${l}`);
+      }
+  }
+  if (res.manual.length > 0) {
+    console.warn('patterns-subpath: cannot rewrite these, do them by hand:');
+    for (const l of manualLines) console.warn(l);
+  }
+  return 0;
+}
+
+// Compare real paths: npm/yarn link the bin and pnpm links the package directory, so
+// argv[1] is a symlink while import.meta.url is already resolved.
+const isEntry = (() => {
+  try {
+    return (
+      !!process.argv[1] &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+if (isEntry) {
+  process.exit(main(process.argv.slice(2)));
+}

package/codemods/patterns-subpath.names.json

@@ -0,0 +1,26 @@
+{
+  "subpath": "@hirobius/design-system/patterns",
+  "names": [
+    "ActivityFeed",
+    "AppShell",
+    "AssetImg",
+    "Calendar",
+    "Carousel",
+    "CodeBlock",
+    "CommandPalette",
+    "DocLinkCard",
+    "ErrorPattern",
+    "FileInput",
+    "Form",
+    "Lightbox",
+    "NavItem",
+    "OverflowList",
+    "Page",
+    "Reveal",
+    "SideNav",
+    "Stepper",
+    "Toolbar",
+    "TopNav",
+    "TreeList"
+  ]
+}

package/package.json

@@ -20,7 +20,7 @@
   "author": "Adrian Milsap",
   "license": "SEE LICENSE IN NOTICE.md",
   "private": false,
-  "version": "0.17.0",
+  "version": "0.18.0",
   "engines": {
     "node": ">=20",
     "pnpm": ">=8"
@@ -97,7 +97,9 @@
     "dist",
     "NOTICE.md",
     "hirobius.tokens.json",
-    "public/hds-manifest.json"
+    "public/hds-manifest.json",
+    "codemods/patterns-subpath.mjs",
+    "codemods/patterns-subpath.names.json"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -232,6 +234,9 @@
   "lint-staged": {
     "*.{ts,tsx,js,jsx,mjs,cjs,json,md,mdx,css,scss,html,yaml,yml}": "prettier --write"
   },
+  "bin": {
+    "hds-patterns-subpath": "codemods/patterns-subpath.mjs"
+  },
   "scripts": {
     "_comment:a11y-high-value": "The following check:* validators are high-value accessibility checks that catch real violations (check:focus found 1 missing focus class). Kept dormant/manual-only to avoid pre-commit performance regression. Candidates to wire into pretest after CI stability review.",
     "_comment:editorconfig-version": "check:mojibake routes through scripts/lib/mojibake.mjs, which pins EC_VERSION=v3.7.0. The editorconfig-checker@6.1.x npm wrapper expects binary v3.7.0 but downloads the latest Go release (v3.8.0, 2026-06-25), so a fresh install fails with a version mismatch (binary != config). Pinning the download to the wrapper's expected version keeps CI + pre-commit green. Bump both together when upgrading the npm package. The wrapper also SKIPS gracefully (like check:secrets) when the binary download is network-blocked (remote agent sessions), so hooks no longer need --no-verify (#18/#52); the gate still enforces wherever the binary is present.",
@@ -386,6 +391,8 @@
     "validate:manifest": "node scripts/validate-manifest.mjs",
     "visual-ingest": "node scripts/visual-ingest.mjs",
     "watch:guardrails": "nodemon --watch CLAUDE.md --watch .cursorrules --watch eslint.config.js --watch .github/workflows -e md,json,js,yml,yaml --exec \"node scripts/audit-guardrails.js\"",
-    "watch:metrics": "nodemon --watch src/app/components --watch src/app/pages --watch src/app/design-system --watch src/app/styles -e tsx,ts,css --exec \"node scripts/audit-tokens.mjs --full && node scripts/generate-manifest.mjs\""
+    "watch:metrics": "nodemon --watch src/app/components --watch src/app/pages --watch src/app/design-system --watch src/app/styles -e tsx,ts,css --exec \"node scripts/audit-tokens.mjs --full && node scripts/generate-manifest.mjs\"",
+    "consumer:usage": "node scripts/count-consumer-usage.mjs",
+    "codemod:names": "node scripts/build-codemod-pattern-names.mjs"
   }
 }