@weatherboard/gyde-design 0.3.0

package/stylex.mjs

@@ -0,0 +1,178 @@
+/**
+ * G-100 — StyleX is the mandated styling layer.
+ *
+ * Completes what G-98 began. G-98 banned Tailwind because a utility framework
+ * is an uncontrolled escape hatch out of the token layer; that was a statement
+ * about Tailwind and it left the positive question open. This answers it: there
+ * is one styling implementation, and it is StyleX.
+ *
+ * WHAT WAS ARGUED AGAINST THIS, AND WHAT REMAINS TRUE.
+ *
+ * G-58 Decision 3 rejected the mandate on two measured grounds, and honesty
+ * about them is the point of writing this here rather than only in the ADR:
+ *
+ * 1. **System A reached 98% tokenisation without StyleX** — the
+ *    highest of the three consumers — with a typed dictionary compiled to CSS
+ *    custom properties and no build plugin anywhere. That is still true, and
+ *    this mandate costs them a migration that fixes no measured defect. It is
+ *    the price of one styling layer instead of two, and it was paid
+ *    deliberately.
+ *
+ * 2. **The two-file problem.** `tokens.stylex.ts` cannot import `index.ts`,
+ *    because `defineVars` must resolve statically, so a consumer maintained the
+ *    same values by hand in two files. This one is **answered rather than
+ *    accepted**: `generateStyleX` emits the StyleX module from the same
+ *    dictionary as the CSS, in the same run, so there is no second copy for
+ *    anybody to keep in step. G-58's own words — "the problem not existing
+ *    rather than being solved".
+ *
+ * The first cost stands. A mandate whose costs are only recorded in the
+ * document nobody reads at 2am is a mandate that will be litigated again in six
+ * months by someone who thinks it was never considered.
+ *
+ * THE WIRING IS CHECKED, NOT ASSUMED — AND IT IS THE PART THAT ACTUALLY BREAKS.
+ *
+ * StyleX is a compiler. A project that declares the dependency and imports the
+ * API but never wires the plugin gets **no styles at all**: `stylex.create`
+ * returns objects, `stylex.props` returns class names, nothing throws, the
+ * build passes, and the page renders unstyled. It is the same failure shape as
+ * G-98's dependency removal and as `wiring.mjs`'s missing stylesheet — the
+ * third time this class of defect has appeared in this codebase, which is why
+ * it is checked rather than trusted.
+ *
+ * @gyde-emits-source-for-another-repo — the fixtures beside this file are
+ * package manifests and configuration written as data for another repository.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export const RULE = "styling-layer";
+
+const STYLEX_RUNTIME = /^@stylexjs\/stylex$/;
+const STYLEX_TOOLING = /^@stylexjs\/(babel-plugin|postcss-plugin|webpack-plugin|rollup-plugin|nextjs-plugin|esbuild-plugin|open-props)$/;
+
+/**
+ * Styling layers that compete with StyleX for the same job.
+ *
+ * CSS Modules and plain stylesheets are deliberately absent: they carry the
+ * generated custom properties and are how the token layer reaches the page. The
+ * ban is on a SECOND way to express a component's styles, not on CSS.
+ */
+const COMPETING = {
+  "styled-components": "runtime CSS-in-JS",
+  "@emotion/react": "runtime CSS-in-JS",
+  "@emotion/styled": "runtime CSS-in-JS",
+  "@vanilla-extract/css": "a second compile-time CSS-in-JS",
+  "@stitches/react": "runtime CSS-in-JS",
+  "linaria": "a second compile-time CSS-in-JS",
+  "@linaria/core": "a second compile-time CSS-in-JS",
+  "jss": "runtime CSS-in-JS",
+};
+
+const CONFIG_HINT = /stylex/i;
+const CONFIG_FILES = /^(next\.config\.(js|mjs|ts)|vite\.config\.(js|mjs|ts)|babel\.config\.(js|json|cjs)|\.babelrc(\.js|\.json)?|postcss\.config\.(js|cjs|mjs))$/;
+
+function manifestOf(root, pkgPath) {
+  const p = join(root, pkgPath === "." ? "" : pkgPath, "package.json");
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+const allDeps = (json) => ({
+  ...(json.dependencies || {}), ...(json.devDependencies || {}), ...(json.peerDependencies || {}),
+});
+
+/**
+ * Is the styling layer StyleX, is it wired, and is anything competing with it?
+ *
+ * `renders` narrows the check to packages that actually render UI — the same
+ * set `wiring.mjs` uses. A utility package with no components does not need a
+ * styling layer, and demanding one there is how a mandate gets a reputation for
+ * being about compliance rather than about the product.
+ */
+export function checkStyleX(root, { packages = [], renders = null } = {}) {
+  const scope = renders ? packages.filter((p) => renders.includes(p.path)) : packages;
+
+  if (scope.length === 0) {
+    return {
+      unknown: true,
+      why: renders
+        ? "no package in this workspace renders UI, so there is no styling layer to mandate"
+        : "which packages render UI is not known, so the mandate cannot be scoped",
+      missing: [], unwired: [], competing: [],
+    };
+  }
+
+  const missing = [];
+  const unwired = [];
+  const competing = [];
+
+  for (const pkg of scope) {
+    const json = manifestOf(root, pkg.path);
+    if (!json) continue;
+    const deps = allDeps(json);
+
+    const hasRuntime = Object.keys(deps).some((n) => STYLEX_RUNTIME.test(n));
+    const hasTooling = Object.keys(deps).some((n) => STYLEX_TOOLING.test(n));
+
+    for (const [name, why] of Object.entries(COMPETING)) {
+      if (deps[name]) competing.push({ package: pkg.path, name, version: deps[name], why });
+    }
+
+    if (!hasRuntime) { missing.push({ package: pkg.path }); continue; }
+
+    // A compiler that is installed and not wired produces no styles and no
+    // error. Checked here rather than trusted, because this is the third time
+    // this codebase has met the same shape (G-98, wiring.mjs, and now this).
+    if (!hasTooling && !configMentionsStyleX(root, pkg.path)) {
+      unwired.push({ package: pkg.path });
+    }
+  }
+
+  return {
+    unknown: false,
+    missing, unwired, competing,
+    packagesChecked: scope.length,
+    ok: missing.length === 0 && unwired.length === 0 && competing.length === 0,
+  };
+}
+
+function configMentionsStyleX(root, pkgPath) {
+  const dir = join(root, pkgPath === "." ? "" : pkgPath);
+  let entries; try { entries = readdirSync(dir); } catch { return false; }
+  for (const name of entries) {
+    if (!CONFIG_FILES.test(name)) continue;
+    try { if (CONFIG_HINT.test(readFileSync(join(dir, name), "utf8"))) return true; } catch { /* unreadable */ }
+  }
+  return false;
+}
+
+export function stylexFindings(result) {
+  if (result.unknown) return [];
+  const at = (p) => `${p === "." ? "" : p + "/"}package.json`;
+  return [
+    ...result.missing.map((m) => ({ file: at(m.package), rule: RULE, line: null, raw: "@stylexjs/stylex", kind: "missing" })),
+    ...result.unwired.map((u) => ({ file: at(u.package), rule: RULE, line: null, raw: "stylex-plugin", kind: "unwired" })),
+    ...result.competing.map((c) => ({ file: at(c.package), rule: RULE, line: null, raw: c.name, kind: "competing" })),
+  ];
+}
+
+export function formatStyleX(result) {
+  if (result.unknown) return `styling layer could not tell — ${result.why}`;
+  if (result.ok) return `styling layer StyleX, wired, in all ${result.packagesChecked} package(s) that render UI`;
+
+  const L = [`styling layer ${result.missing.length + result.unwired.length + result.competing.length} problem(s) across ${result.packagesChecked} UI package(s)`];
+  for (const m of result.missing) L.push(`             ${m.package}  no @stylexjs/stylex — StyleX is the mandated styling layer (G-100)`);
+  for (const u of result.unwired) L.push(`             ${u.package}  StyleX installed but no plugin and no config mentioning it`);
+  for (const c of result.competing) L.push(`             ${c.package}  ${c.name}@${c.version} — ${c.why}, competing with StyleX`);
+
+  if (result.unwired.length) {
+    L.push("");
+    L.push("  StyleX is a compiler. Installed and unwired it produces NO styles and no");
+    L.push("  error: create returns objects, props returns class names, the build passes,");
+    L.push("  and the page renders unstyled. That is the same failure as removing a");
+    L.push("  Tailwind dependency with classes still in source.");
+  }
+  return L.join("\n");
+}

package/tailwind.mjs

@@ -0,0 +1,238 @@
+/**
+ * G-98 — Tailwind is not a permitted styling layer.
+ *
+ * Reverses G-58 Decision 3, which left the styling layer unmandated. That
+ * decision was correct on the evidence it had and this one is a product
+ * decision rather than a measurement: Gyde must own the token layer completely,
+ * and a utility framework is a standing escape hatch out of it. `p-[13px]`
+ * needs no approval, leaves no trace in a dictionary, and is one keystroke away
+ * from every call site.
+ *
+ * THE ORDERING IS THE WHOLE DESIGN, AND IT IS NOT OBVIOUS.
+ *
+ * Tailwind exists in a repository at four levels, and they are removed in the
+ * opposite order to the one people reach for:
+ *
+ *   1. the DEPENDENCY   `tailwindcss` in a package.json
+ *   2. the CONFIG       tailwind.config.*, or an `@import "tailwindcss"`
+ *   3. the CLASSES      `p-4`, `rounded-lg`, `bg-muted` in source
+ *   4. the STYLESHEETS  `@apply p-4`, `theme(spacing.4)` in CSS
+ *
+ * The fourth was missed on the first pass and is the one that makes the ban a
+ * fiction if left out: a repository can hold nothing in any manifest, no
+ * config, and not one utility class in any component, and still be written in
+ * Tailwind — `.card { @apply p-4 rounded-lg bg-muted; }`.
+ *
+ * The obvious first move is to delete the dependency, because it is one line
+ * and it makes the ban pass. It is also the single most destructive thing
+ * anybody could do here. Utility classes are inert strings in a `className`
+ * attribute: with the dependency gone nothing throws, no build fails, no type
+ * errors — every one of those classes silently resolves to no style at all and
+ * the application renders unstyled. One consumer has 4,842 of them.
+ *
+ * So this check refuses to be satisfied in the wrong order. It reports the
+ * dependency as removable ONLY when the classes are gone, and until then it
+ * says so in the finding itself. A gate that can be passed by an action that
+ * breaks production is not a gate, it is a trap — and CHARTER §5's rule applies
+ * here in an unusual direction: "the ban is satisfied" and "the styling has
+ * been removed" must never render the same.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO.
+ *
+ * It does not migrate anything, and it does not count utility classes as a new
+ * finding class. They are already counted — `normalise.mjs` reduces them to
+ * declarations and the existing rules judge them. Adding a second count of the
+ * same code would double the debt and move the ratchet for a reason that is not
+ * a change in the code.
+ *
+ * @gyde-emits-source-for-another-repo — the fixtures beside this file are
+ * package manifests and CSS written as data for a repository that is not this one.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export const RULE = "tailwind-present";
+
+/** Package names that ARE Tailwind, rather than merely mentioning it. */
+const TAILWIND_PACKAGE = /^(tailwindcss|@tailwindcss\/.+)$/;
+
+/** A plugin is only Tailwind's problem while Tailwind is there; it is not itself the ban. */
+const TAILWIND_PLUGIN = /^(prettier-plugin-tailwindcss|tailwind-merge|tailwind-variants|clsx)$/;
+
+const CONFIG_NAMES = /^tailwind\.config\.(js|cjs|mjs|ts)$/;
+
+/** `@import "tailwindcss"` / `@tailwind base` — the v4 and v3 spellings. */
+const CSS_ENTRY = /@import\s+["']tailwindcss["']|@tailwind\s+(base|components|utilities)\b/;
+
+/**
+ * Where Tailwind is declared, configured, and used.
+ *
+ * `utilityClasses` is passed in rather than counted here. `normalise.mjs`
+ * already reduces utilities to declarations and is the one place that knows
+ * what a Tailwind class is; counting them again here would be a second
+ * implementation of the same question, free to disagree with the first.
+ */
+export function detectTailwind(root, { packages = [], utilityClasses = null, cssDirectives = null } = {}) {
+  const dependencies = [];
+  const plugins = [];
+
+  for (const pkg of packages) {
+    const manifest = join(root, pkg.path === "." ? "" : pkg.path, "package.json");
+    if (!existsSync(manifest)) continue;
+    let json; try { json = JSON.parse(readFileSync(manifest, "utf8")); } catch { continue; }
+
+    for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+      for (const [name, version] of Object.entries(json[field] || {})) {
+        if (TAILWIND_PACKAGE.test(name)) dependencies.push({ package: pkg.path, name, version, field });
+        else if (TAILWIND_PLUGIN.test(name)) plugins.push({ package: pkg.path, name, version, field });
+      }
+    }
+  }
+
+  const configs = [];
+  for (const pkg of packages) {
+    const dir = join(root, pkg.path === "." ? "" : pkg.path);
+    let entries; try { entries = readdirSync(dir); } catch { continue; }
+    for (const name of entries) if (CONFIG_NAMES.test(name)) configs.push(`${pkg.path === "." ? "" : pkg.path + "/"}${name}`);
+  }
+
+  return { dependencies, plugins, configs, utilityClasses, cssDirectives, ...verdict({ dependencies, configs, utilityClasses, cssDirectives }) };
+}
+
+/** Does a stylesheet pull Tailwind in? Exported so a caller can walk CSS without this module walking twice. */
+export const importsTailwind = (css) => CSS_ENTRY.test(css);
+
+function verdict({ dependencies, configs, utilityClasses, cssDirectives }) {
+  const present = dependencies.length > 0 || configs.length > 0;
+  if (!present) return { present: false, safeToRemove: null, why: "Tailwind is not installed" };
+
+  // The load-bearing branch. Not knowing how many classes remain is not the
+  // same as knowing there are none, and only one of those is safe to act on.
+  // A stylesheet directive breaks on removal exactly as a class does, so
+  // "no classes left" is not the same as "safe". Counting only one of the two
+  // is how the ordering guard would have been satisfied by a repository that
+  // still stops rendering the moment the dependency goes.
+  if (utilityClasses === null || cssDirectives === null) {
+    return {
+      present: true, safeToRemove: null,
+      why: "Tailwind is installed, and how much still resolves through it is unknown — " +
+           "removing it now could leave every class and directive resolving to nothing",
+    };
+  }
+  if (utilityClasses > 0 || cssDirectives > 0) {
+    const parts = [];
+    if (utilityClasses > 0) parts.push(`${utilityClasses} utility class(es)`);
+    if (cssDirectives > 0) parts.push(`${cssDirectives} stylesheet directive(s)`);
+    return {
+      present: true, safeToRemove: false,
+      why: `Tailwind is installed and ${parts.join(" and ")} still resolve through it. ` +
+           "Remove them first: they fail silently, so nothing throws when the dependency goes",
+    };
+  }
+  return {
+    present: true, safeToRemove: true,
+    why: "nothing resolves through Tailwind any more, so the dependency and config can go",
+  };
+}
+
+/** The finding, shaped like every other so it enters the ledger unchanged. */
+export function tailwindFindings(result) {
+  if (!result.present) return [];
+  return [
+    ...result.dependencies.map((d) => ({
+      file: `${d.package === "." ? "" : d.package + "/"}package.json`,
+      rule: RULE, line: null, raw: d.name, kind: "dependency", detail: `${d.name}@${d.version} in ${d.field}`,
+    })),
+    ...result.configs.map((c) => ({ file: c, rule: RULE, line: null, raw: c, kind: "config", detail: "Tailwind configuration" })),
+  ];
+}
+
+export function formatTailwind(result) {
+  if (!result.present) return "tailwind     not installed";
+
+  const L = [`tailwind     PRESENT — ${result.dependencies.length} declaration(s), ${result.configs.length} config file(s)`];
+  for (const d of result.dependencies) L.push(`             ${d.package}  ${d.name}@${d.version} (${d.field})`);
+  for (const c of result.configs) L.push(`             ${c}`);
+  if (result.plugins.length) {
+    L.push(`             ${result.plugins.length} companion package(s): ${result.plugins.map((p) => p.name).join(", ")}`);
+    L.push("             not the ban themselves — they stop mattering when Tailwind goes");
+  }
+
+  L.push("");
+  if (result.safeToRemove === true) {
+    L.push("  SAFE TO REMOVE. No utility class resolves through Tailwind any more.");
+  } else if (result.safeToRemove === false) {
+    L.push("  DO NOT REMOVE THE DEPENDENCY YET.");
+    if (result.utilityClasses > 0) L.push(`    ${result.utilityClasses} utility class(es) — inert strings in a className attribute`);
+    if (result.cssDirectives > 0) L.push(`    ${result.cssDirectives} stylesheet directive(s) — @apply and friends, which stop compiling`);
+    L.push("  Deleting the dependency throws nothing, fails no build, and renders the");
+    L.push("  application unstyled. Remove these first, then the config, then the dependency.");
+  } else {
+    L.push(`  ${result.why}.`);
+  }
+  return L.join("\n");
+}
+
+export const CSS_RULE = "tailwind-in-css";
+
+/**
+ * Tailwind's vocabulary, carried in a stylesheet.
+ *
+ * The hole G-98 and G-100 both recorded and neither closed. A repository can
+ * satisfy the dependency ban completely — nothing in any manifest, no config,
+ * not one utility class in any JSX file — and still be written in Tailwind:
+ *
+ *   .card { @apply p-4 rounded-lg bg-muted; }
+ *
+ * That is the ban being satisfiable without the thing it bans being gone, which
+ * is the same trap the removal-ordering guard above exists to prevent. A gate
+ * with a documented way through it is a gate that teaches people the way
+ * through it.
+ *
+ * WHAT IS AND IS NOT TAILWIND HERE.
+ *
+ * `@layer` is NOT included, and that is the one to get right: it is standard
+ * CSS cascade layers, it appears in stylesheets that have never seen Tailwind,
+ * and flagging it would make this rule fire on the CSS the mandate is asking
+ * people to write. The directives below have no meaning outside Tailwind's
+ * compiler, so their presence is not a guess.
+ *
+ * `theme()` is included with the same reasoning: it is a compile-time lookup
+ * into Tailwind's config, so a stylesheet using it cannot be read without
+ * Tailwind, whatever the manifest says.
+ */
+const CSS_DIRECTIVE = /(^|[\s;{}])@(apply|tailwind|screen|variants|responsive|config)\b|(^|[^\w-])theme\s*\(/;
+
+/** Strip comments, preserving line count so a finding points at the right line. */
+const stripCss = (text) => text.replace(/\/\*[\s\S]*?\*\//g, (s) => s.replace(/[^\n]/g, " "));
+
+export function tailwindInCss(text, { filename = "" } = {}) {
+  const found = [];
+  stripCss(text).split("\n").forEach((line, i) => {
+    const m = line.match(CSS_DIRECTIVE);
+    if (!m) return;
+    const directive = (m[2] ? "@" + m[2] : "theme()");
+    found.push({
+      file: filename, rule: CSS_RULE, line: i + 1,
+      raw: directive, directive, source: line.trim(),
+    });
+  });
+  return found;
+}
+
+export function formatTailwindCss(findings) {
+  if (findings.length === 0) return "no stylesheet carries Tailwind's vocabulary";
+  const byFile = {};
+  for (const f of findings) (byFile[f.file] ??= []).push(f);
+  const L = [`${findings.length} Tailwind directive(s) in ${Object.keys(byFile).length} stylesheet(s):`];
+  for (const [file, fs] of Object.entries(byFile)) {
+    L.push(`  ${file}  ${[...new Set(fs.map((f) => f.directive))].join(", ")} (${fs.length})`);
+  }
+  L.push("");
+  L.push("  A repository can pass the dependency ban with no manifest entry, no config and");
+  L.push("  no utility class in any component, and still be written in Tailwind. These");
+  L.push("  directives have no meaning outside its compiler, so the stylesheet stops");
+  L.push("  working the moment the dependency goes — silently, like the classes.");
+  return L.join("\n");
+}