@uxfront/layer-docs 0.2.1 → 0.4.0

package/test/no-brand-leakage.test.ts

@@ -0,0 +1,124 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * The Storybook embed is the layer's most leak-prone surface: it is the only
+ * component whose whole job is to address somebody else's deployment. A default
+ * host "just for now", or a message name copied out of the repo it came from,
+ * breaks no build — it points the *next* consumer's docs at the previous
+ * consumer's Storybook, quietly. So it is a test, not a review habit.
+ *
+ * Three assertions, matching the three shapes the leak takes:
+ *
+ * 1. The embed's own source names no consumer.
+ * 2. Nothing in the package hardcodes a Storybook host.
+ * 3. Nothing in the package speaks a branded message namespace.
+ *
+ * Scopes differ on purpose. (1) is narrow because naming a consumer in a
+ * comment elsewhere is often a receipt — "+26.7 KB gzip on <consumer>,
+ * UXF-118" is evidence, not branding, and a guard that banned it would be
+ * training people to delete their sources. (2) and (3) are package-wide because
+ * a hardcoded host or a branded message name is a defect wherever it appears.
+ */
+
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+/** The embed surface: the files that exist to talk to a consumer's Storybook. */
+const EMBED_SOURCES = [
+  "app/components/content/StorybookEmbed.vue",
+  "app/utils/storybookEmbed.ts",
+  "storybook/index.ts",
+];
+
+/**
+ * Products that extend this layer. A match inside the embed surface means the
+ * neutral component learned something about a specific consumer.
+ */
+const CONSUMER_BRANDS = ["styleframe", "inkline"];
+
+/** Hostnames that exist only to be read, never fetched. */
+const DOCUMENTATION_HOSTS = ["example.com", "example.org", "localhost", "127.0.0.1"];
+
+/** The one namespace the package is allowed to speak. */
+const NEUTRAL_NAMESPACE = "uxfront:docs-embed";
+
+/**
+ * Any `<namespace>:theme` / `:height` / `:preview-height` string literal — the
+ * shape of this contract's message names, whoever coined them.
+ *
+ * Quoted strings only, not backticked ones: backticks here mark prose in doc
+ * comments, and a real message name built as a template literal is
+ * parameterized (`${namespace}:theme`) rather than branded.
+ */
+const MESSAGE_NAME_LITERAL = /["']([\w.-]+):(?:theme|height|preview-height)["']/g;
+
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".nuxt", ".output", "dist"]);
+const SOURCE_EXTENSIONS = [".ts", ".vue", ".css", ".json"];
+
+interface SourceFile {
+  path: string;
+  source: string;
+}
+
+function readSourceFiles(directory: string, collected: SourceFile[] = []): SourceFile[] {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRECTORIES.has(entry.name)) readSourceFiles(path, collected);
+      continue;
+    }
+    if (!SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))) continue;
+    // Tests quote the literals they exercise — including a legacy namespace,
+    // which is the whole point of the compat-window cases.
+    if (entry.name.endsWith(".test.ts")) continue;
+
+    collected.push({ path: relative(PACKAGE_ROOT, path), source: readFileSync(path, "utf8") });
+  }
+
+  return collected;
+}
+
+describe("no brand leakage in the Storybook embed", () => {
+  const files = readSourceFiles(PACKAGE_ROOT);
+  const embedFiles = files.filter((file) => EMBED_SOURCES.includes(file.path));
+
+  // Guards the guard: a scan that silently matched nothing passes everything.
+  it("finds the embed surface and the rest of the package", () => {
+    expect(embedFiles.map((file) => file.path).sort()).toEqual([...EMBED_SOURCES].sort());
+    expect(files.length).toBeGreaterThan(50);
+  });
+
+  it.each(CONSUMER_BRANDS)("names no consumer (%s) in the embed surface", (brand) => {
+    const pattern = new RegExp(brand, "i");
+    const offenders = embedFiles
+      .filter((file) => pattern.test(file.source))
+      .map((file) => file.path);
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("hardcodes no Storybook host — where one is deployed is consumer config", () => {
+    const offenders = files.flatMap((file) =>
+      [...file.source.matchAll(/https?:\/\/[^\s"'`)]+/g)]
+        .map((match) => match[0])
+        .filter((url) => /storybook/i.test(url))
+        .filter((url) => !DOCUMENTATION_HOSTS.some((host) => url.includes(host)))
+        .map((url) => `${file.path}: ${url}`),
+    );
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("speaks no branded message namespace", () => {
+    const offenders = files.flatMap((file) =>
+      [...file.source.matchAll(MESSAGE_NAME_LITERAL)]
+        .filter((match) => match[1] !== NEUTRAL_NAMESPACE)
+        .map((match) => `${file.path}: ${match[0]}`),
+    );
+
+    expect(offenders).toEqual([]);
+  });
+});

package/utils/accent.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+/** Fallback accent when the brand token cannot be resolved. */
+export const FALLBACK_ACCENT = "#ffffff";
+
+/**
+ * Resolve the brand accent colour as a literal, build-time string.
+ *
+ * OG images are rendered by satori, which has no CSS cascade and no custom
+ * properties: `var(--ui-primary)` resolves to nothing. A dynamic Tailwind class
+ * is worse than useless, because every consumer *shadows* a stock Tailwind
+ * scale name with its own value — `--color-teal: hsl(189 53% 41%)` is not
+ * Tailwind's teal, so `text-teal-500` would render the wrong brand. The colour
+ * therefore has to arrive already resolved.
+ *
+ * It is read out of the consumer's CSS entry by following the same two hops the
+ * browser does, and that `describeBrandPaletteCss` already asserts:
+ *
+ *   `@theme static { --color-teal: hsl(189, 53%, 41%); }`  — the literal
+ *   `:root { --ui-primary: var(--color-teal); }`           — the alias
+ *
+ * Reading the CSS rather than `ui.colors.primary` is deliberate: `app.config.ts`
+ * is not merged into `nuxt.options.appConfig` at module-setup time (that object
+ * holds only `nuxt.config.ts`'s own `appConfig` key), so the scale name is not
+ * available there. The CSS is available, it is the definition rather than a
+ * discriminant, and it needs no configuration from the consumer at all.
+ *
+ * Shade variants are deliberately not followed: they are declared with
+ * relative-colour syntax (`hsl(from var(--color-teal) h s 60%)`), which satori
+ * cannot parse either.
+ */
+export function resolveBrandAccent(options: {
+  /** The consumer's registered CSS entries (`nuxt.options.css`). */
+  cssEntries: string[];
+  /** Consumer root, used to resolve relative CSS entry paths. */
+  rootDir: string;
+}): { accent: string; reason?: string } {
+  const { cssEntries, rootDir } = options;
+
+  for (const entry of cssEntries) {
+    const path = isAbsolute(entry) ? entry : join(rootDir, entry.replace(/^\.\//, ""));
+    if (!existsSync(path)) {
+      continue;
+    }
+    const accent = readAccent(readFileSync(path, "utf8"));
+    if (accent) {
+      return { accent };
+    }
+  }
+
+  return {
+    accent: FALLBACK_ACCENT,
+    reason:
+      "could not resolve `--ui-primary` to a literal colour in the registered " +
+      `CSS entries (${cssEntries.join(", ") || "none"})`,
+  };
+}
+
+/** Follow `--ui-primary` to the literal it aliases, or take it literally. */
+function readAccent(css: string): string | undefined {
+  const uiPrimary = /--ui-primary\s*:\s*([^;}]+)/.exec(css)?.[1]?.trim();
+  if (!uiPrimary) {
+    return undefined;
+  }
+
+  const alias = /^var\(\s*(--[\w-]+)\s*\)$/.exec(uiPrimary)?.[1];
+  if (!alias) {
+    // Already a literal — usable unless it is some other custom-property
+    // expression satori would render as nothing.
+    return uiPrimary.includes("var(") ? undefined : uiPrimary;
+  }
+
+  const declared = new RegExp(`${escapeRegExp(alias)}\\s*:\\s*([^;}]+)`).exec(css)?.[1]?.trim();
+  return declared && !declared.includes("var(") ? declared : undefined;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}