@icomponents/react 0.1.0

package/src/testids.contract.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "bun:test";
+
+import { Glob } from "bun";
+
+import { TESTID } from "./testids";
+
+/**
+ * Страж контракта вёрстки.
+ *
+ * Контракт (`testids.ts`) имеет смысл, только если его КТО-ТО НЕСЁТ. Заменили вёрстку целиком на
+ * прототип, забыли навесить `data-testid` — и сеть тестов обманчиво «позеленеет»: e2e не найдёт экран и
+ * упадёт, а DOM-тесты компонентов, которые перестали использоваться, будут бодро проходить на мёртвом
+ * коде. Этот тест ловит ровно такую ситуацию: он проверяет, что ключевые id ЖИВУТ в исходниках UI, а не
+ * только в файле контракта.
+ *
+ * Покраснел после замены вёрстки — вёрстка не выполнила контракт. Это НЕ «тест устарел».
+ */
+const REPO = new URL("../../..", import.meta.url).pathname;
+
+/**
+ * Где искать вёрстку. В репе КИТА это его собственные компоненты: контракт держит тот, кто рисует
+ * таблицу, диалог подтверждения и оболочку. У приложения свой такой же страж — он сторожит уже
+ * ЕГО экраны, потому что `screen`/`field` навешивает продуктовая вёрстка, а не кит.
+ */
+const UI_ROOTS = ["packages/react/src"];
+
+/** Без этих id тест не может ни найти экран, ни адресовать строку, ни подтвердить действие. */
+const REQUIRED = [
+  TESTID.screen,
+  TESTID.screenTitle,
+  TESTID.table,
+  TESTID.tableEmpty,
+  TESTID.confirmDialog,
+  TESTID.confirmAccept,
+  TESTID.confirmCancel,
+];
+
+async function uiSources(): Promise<string> {
+  let all = "";
+  for (const root of UI_ROOTS) {
+    const cwd = `${REPO}/${root}`;
+    try {
+      for await (const rel of new Glob("**/*.tsx").scan({ cwd })) {
+        if (rel.endsWith(".test.tsx")) continue;
+        all += await Bun.file(`${cwd}/${rel}`).text();
+      }
+    } catch {
+      // каталога нет в этом продукте — пропускаем, а не роняем прогон
+    }
+  }
+  return all;
+}
+
+/** Обратное отображение значение → имя ключа: тест ищет ИСПОЛЬЗОВАНИЕ константы, а не строку-литерал. */
+function nameOf(value: string): string {
+  const entry = Object.entries(TESTID).find(([, v]) => v === value);
+  return entry ? entry[0] : value;
+}
+
+describe("контракт вёрстки: data-testid живут в UI, а не только в testids.ts", () => {
+  it("каждый обязательный testid где-то навешен", async () => {
+    const src = await uiSources();
+    expect(REQUIRED.filter((id) => !src.includes(`TESTID.${nameOf(id)}`))).toEqual([]);
+  });
+
+  it("строку списка можно адресовать по id сущности (row-<id>)", async () => {
+    // Без этого тест сможет проверить только «третью строку сверху» — а порядок сортировки не контракт.
+    expect(await uiSources()).toContain("TESTID.tableRow(");
+  });
+
+  /**
+   * `field-<name>` и `form-submit` здесь НЕ проверяются, и это разделение ответственности, а не
+   * послабление: поля рисуют формы продукта (вход, экраны слайсов), кит даёт только примитив
+   * `<Input>`, которому нечего называть. Требование живёт в страже приложения — там, где есть формы.
+   * Если однажды кит начнёт собирать формы сам, проверку возвращать сюда.
+   */
+  it("страж покрывает ровно ту вёрстку, за которую отвечает кит", async () => {
+    const src = await uiSources();
+    expect(src).toContain("TESTID.confirmDialog");
+    expect(src).toContain("TESTID.navItem(");
+  });
+
+  /**
+   * Хваталки СВОИХ действий объявляет слайс, который ими владеет, — в своём пакете. Проверять их здесь
+   * поимённо было бы неверно: список пришлось бы править в ядре при каждом новом слайсе, а ядро
+   * перезаписывается синком. Поэтому страж находит модули `testids.ts` слайсов САМ и требует, чтобы
+   * каждый объявленный в них ключ действительно использовался. Объявленный и не навешенный id — это
+   * действие, которое никакой тест не проверяет.
+   */
+  it("каждый ключ, объявленный слайсом в своём testids.ts, используется в вёрстке", async () => {
+    const src = await uiSources();
+    const unused: string[] = [];
+
+    for (const root of UI_ROOTS) {
+      if (root.startsWith("packages/ui")) continue; // ядро проверено списком REQUIRED выше
+      const cwd = `${REPO}/${root}`;
+      try {
+        for await (const rel of new Glob("**/testids.ts").scan({ cwd })) {
+          const text = await Bun.file(`${cwd}/${rel}`).text();
+          // Имена ключей объявления: `noteAction: (…)` / `statusFilter: "…"`.
+          for (const match of text.matchAll(/^\s{2}(\w+):/gm)) {
+            const key = match[1]!;
+            if (!src.includes(`.${key}`)) unused.push(`${root}/${rel} → ${key}`);
+          }
+        }
+      } catch {
+        // каталога нет — пропускаем
+      }
+    }
+
+    expect(unused).toEqual([]);
+  });
+});

package/src/testids.ts

@@ -0,0 +1,8 @@
+/**
+ * Контракт вёрстки живёт в `@icomponents/tokens` — он платформо-независим: те же `data-testid`
+ * понадобятся и React Native-реализации, а дублировать контракт значит развести две правды.
+ *
+ * Здесь остаётся реэкспорт, потому что путь `@icomponents/react/testids` — публичная поверхность,
+ * на которую уже ссылаются приложения и их тесты.
+ */
+export * from "@icomponents/tokens/testids";

package/src/theme-contract.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "bun:test";
+
+import { Glob } from "bun";
+
+/**
+ * Контракт темы: цвет живёт в ТОКЕНАХ, а не в компонентах.
+ *
+ * Этот тест написан перед перекраской в тему прототипа — и именно ради неё. Перекраска меняет
+ * значения токенов в `theme.css`; компоненты при этом трогать не нужно. Но ровно в такой момент
+ * появляется соблазн «быстренько» вписать нужный оттенок прямо в компонент — и тогда экран, который
+ * забыли, навсегда останется прежнего цвета, а в тёмной теме станет нечитаемым. Снаружи это выглядит
+ * не как ошибка, а как «дизайн такой».
+ *
+ * Поэтому: `#hex`, `rgb(...)` и `hsl(...)` в компонентах запрещены. Исключение — SVG-ассеты: там цвет
+ * часть самой картинки, а не оформления.
+ */
+/**
+ * Контракт живёт в дизайн-системе (ядро, синкается в продукты), но сканирует ВЕСЬ UI: правило про
+ * цвет бессмысленно, если его соблюдают только компоненты kit'а, а экраны слайсов зашивают свои
+ * оттенки. Каталоги, которых в продукте нет, просто пропускаются.
+ */
+const REPO = new URL("../../..", import.meta.url).pathname;
+const UI_ROOTS = [
+  "packages/ui/src",
+  "packages/iam/src/features",
+  "packages/billing/src/ui",
+  "packages/dashboard/src/ui",
+  "apps/web/src/client",
+];
+
+/**
+ * Сырой цвет — это `#hex` и `rgb()/hsl()` с ЧИСЛАМИ. А `hsl(var(--sidebar-border))` — это токен:
+ * функция лишь разворачивает переменную, и при перекраске он поменяется вместе с темой.
+ */
+const RAW_HEX = /#[0-9a-fA-F]{3,8}\b/;
+const RAW_FN = /\b(rgba?|hsla?)\(\s*(?!var\()/;
+const hasRawColor = (src: string): boolean => RAW_HEX.test(src) || RAW_FN.test(src);
+
+/** Ассеты — картинки: их цвета не «оформление», а содержимое. Тесты — не продакшен-код. */
+const EXEMPT = /(^|\/)assets\/|\.test\.tsx?$|\.css$/;
+
+async function componentSources(): Promise<{ file: string; text: string }[]> {
+  const out: { file: string; text: string }[] = [];
+  for (const root of UI_ROOTS) {
+    const cwd = `${REPO}/${root}`;
+    try {
+      for await (const rel of new Glob("**/*.{ts,tsx}").scan({ cwd })) {
+        if (EXEMPT.test(rel)) continue;
+        out.push({ file: `${root}/${rel}`, text: await Bun.file(`${cwd}/${rel}`).text() });
+      }
+    } catch {
+      // каталога нет в этом продукте — правило к нему не применяется
+    }
+  }
+  return out;
+}
+
+describe("тема — цвет в токенах, а не в компонентах (NFR-DESIGN)", () => {
+  it("ни один компонент не зашивает сырой цвет (#hex / rgb() / hsl())", async () => {
+    const offenders = (await componentSources())
+      .filter((f) => hasRawColor(stripComments(f.text)))
+      .map((f) => f.file);
+
+    // Если этот тест покраснел во время перекраски — значит цвет прототипа попал в компонент.
+    // Правильное место для него — переменная в theme.css, иначе экран, который забыли, останется
+    // старого цвета навсегда.
+    expect(offenders).toEqual([]);
+  });
+});
+
+const stripComments = (src: string): string =>
+  src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");