@multiplatform.one/config 7.4.0 → 7.5.0

package/oxlint.d.ts

@@ -0,0 +1,12 @@
+export const COLOR_LITERAL: RegExp;
+export const PALETTE_FILE: RegExp;
+export const CHROME_PROPS: readonly string[];
+export const LAYOUT_PROPS: readonly string[];
+export function isPaletteModule(filename: string | undefined): boolean;
+export function matchColorLiteral(value: unknown): string | undefined;
+export const plugin: {
+  meta?: { name?: string };
+  rules?: Record<string, unknown>;
+};
+declare const defaultExport: typeof plugin;
+export default defaultExport;

package/oxlint.mjs

@@ -0,0 +1,183 @@
+/**
+ * Oxlint JS plugin — multiplatform.one convention rules.
+ *
+ * Consuming apps enable it with one config line:
+ *
+ *   { "jsPlugins": ["@multiplatform.one/config/oxlint"] }
+ *
+ * Rules:
+ *   mpo-conventions/no-hex-literals — ban #rgb/#rrggbb(/aa) and rgb()/hsl()
+ *     string literals. Palette modules (themes/base, themes/accent, and
+ *     files whose name contains "palette") are exempt: a 12-step ramp is
+ *     the deliverable.
+ *   mpo-conventions/no-raw-typography — AN-8: app text never rides raw
+ *     Tamagui*-prefixed typography escape hatches (TamaguiText, TamaguiHeading,
+ *     TamaguiH1…, TamaguiParagraph, TamaguiSizableText, TamaguiAnchor) outside
+ *     public/. House Text/Heading shadows are the bare names (MPO-20).
+ *
+ * MPO-17 (no-chrome-props / no-raw-geometry) will add rules to this same
+ * plugin. The chrome/layout vocabularies below are the export surface those
+ * rules will use; they are not enforced yet.
+ */
+
+/** Hex + functional CSS colour literals. AST-visited only (not a text scan). */
+export const COLOR_LITERAL =
+  /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|(?:rgba?|hsla?)\([^)]*\)/i;
+
+/** Palette modules where a 12-step ramp in hex/hsl is the deliverable (EN-2). */
+export const PALETTE_FILE =
+  /(?:^|\/)themes\/(base|accent)\.(tsx?|jsx?)$|(?:^|\/)[^/]*palette[^/]*\.(tsx?|jsx?)$/i;
+
+const RAW_TYPOGRAPHY_HATCH = /^Tamagui(?:Text|SizableText|Paragraph|Heading|H[1-6]|Anchor)$/;
+
+/**
+ * Chrome props MPO-17 `no-chrome-props` will ban on imported
+ * `@multiplatform.one/*` components (including Tamagui shorthands).
+ * Layout composition through `{...props}` stays legal.
+ */
+export const CHROME_PROPS = Object.freeze([
+  "backgroundColor",
+  "bg",
+  "borderColor",
+  "bc",
+  "borderWidth",
+  "bw",
+  "borderRadius",
+  "br",
+  "shadowColor",
+  "shadowOffset",
+  "shadowOpacity",
+  "shadowRadius",
+  "elevation",
+  "fontFamily",
+  "ff",
+  "fontWeight",
+  "fow",
+  "color",
+]);
+
+/**
+ * Layout props callers may pass through the sanctioned `{...props}` hatch.
+ * Sibling margins are layout; chrome (background, radius, type) is not.
+ */
+export const LAYOUT_PROPS = Object.freeze([
+  "flex",
+  "flexBasis",
+  "flexGrow",
+  "flexShrink",
+  "alignSelf",
+  "alignItems",
+  "justifyContent",
+  "position",
+  "zIndex",
+  "margin",
+  "marginTop",
+  "marginRight",
+  "marginBottom",
+  "marginLeft",
+  "marginHorizontal",
+  "marginVertical",
+]);
+
+/**
+ * @param {string | undefined} filename
+ * @returns {boolean}
+ */
+export function isPaletteModule(filename) {
+  if (!filename) return false;
+  const normalized = filename.replaceAll("\\", "/");
+  return PALETTE_FILE.test(normalized);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined} the matched literal, if any
+ */
+export function matchColorLiteral(value) {
+  if (typeof value !== "string") return undefined;
+  const match = value.match(COLOR_LITERAL);
+  return match?.[0];
+}
+
+/** @type {import("eslint").ESLint.Plugin} */
+export const plugin = {
+  meta: {
+    name: "mpo-conventions",
+  },
+  rules: {
+    "no-hex-literals": {
+      meta: {
+        type: "problem",
+        docs: {
+          description:
+            "Disallow hex / rgb / hsl color literals; use theme tokens / knob recipes instead.",
+        },
+        schema: [],
+        messages: {
+          hex: "Color literal {{value}} is banned. Use theme tokens (e.g. $color10) or semantic ramps.",
+        },
+      },
+      create(context) {
+        const filename = context.filename ?? context.getFilename?.() ?? "";
+        if (isPaletteModule(filename)) {
+          return {};
+        }
+
+        function reportIfColor(node, value) {
+          const matched = matchColorLiteral(value);
+          if (!matched) return;
+          context.report({
+            node,
+            messageId: "hex",
+            data: { value: matched },
+          });
+        }
+
+        return {
+          Literal(node) {
+            if (typeof node.value === "string") {
+              reportIfColor(node, node.value);
+            }
+          },
+          TemplateElement(node) {
+            reportIfColor(node, node.value?.cooked ?? "");
+          },
+        };
+      },
+    },
+    "no-raw-typography": {
+      meta: {
+        type: "problem",
+        docs: {
+          description:
+            "AN-8: never render app text through raw typography. Use the house Text/SizableText/Paragraph/Anchor and Heading/H1-H6 (the bare @multiplatform.one/components names), which carry the typography knobs on every platform.",
+        },
+        schema: [],
+        messages: {
+          rawTypography:
+            "{{name}} is a raw typography escape hatch — knob-dead on every platform (AN-8). Import the bare house name from @multiplatform.one/components instead.",
+        },
+      },
+      create(context) {
+        return {
+          ImportDeclaration(node) {
+            if (node.source?.value !== "@multiplatform.one/components") return;
+            for (const specifier of node.specifiers ?? []) {
+              if (specifier.type !== "ImportSpecifier") continue;
+              const imported = specifier.imported?.name ?? specifier.imported?.value;
+              if (typeof imported === "string" && RAW_TYPOGRAPHY_HATCH.test(imported)) {
+                context.report({
+                  node: specifier,
+                  messageId: "rawTypography",
+                  data: { name: imported },
+                });
+              }
+            }
+          },
+        };
+      },
+    },
+  },
+};
+
+export default plugin;

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@multiplatform.one/config",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "Shared build and test configuration presets for multiplatform.one",
   "keywords": [
     "config",
+    "lint",
     "multiplatform.one",
+    "oxlint",
     "playwright",
     "storybook",
     "tsconfig",
@@ -27,8 +29,13 @@
   "files": [
     "src",
     "lib",
+    "pin-react-require.cjs",
     "tsconfig",
     "README.md",
+    "oxlint.mjs",
+    "oxlint.d.ts",
+    "lint.mjs",
+    "lint.d.ts",
     "!tsconfig/dist",
     "!tsconfig/types",
     "types",
@@ -74,7 +81,13 @@
     "./tsconfig/base.json": "./tsconfig/base.json",
     "./tsconfig/build.json": "./tsconfig/build.json",
     "./tsconfig/app.json": "./tsconfig/app.json",
-    "./react-native-config": "./src/react-native.config.cjs"
+    "./react-native-config": "./src/react-native.config.cjs",
+    "./oxlint": "./oxlint.mjs",
+    "./lint": {
+      "types": "./lint.d.ts",
+      "default": "./lint.mjs",
+      "import": "./lint.mjs"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -87,7 +100,7 @@
     "vite-plugin-external": "^6.2.2",
     "vite-plugin-i18next-loader": "^3.1.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/utils": "7.4.0"
+    "@multiplatform.one/utils": "7.5.0"
   },
   "devDependencies": {
     "tsdown": "^0.21.10",

package/pin-react-require.cjs

@@ -0,0 +1,42 @@
+"use strict";
+
+/**
+ * Vitest workers `require()` CJS deps (use-sync-external-store) without
+ * going through Vite aliases. The factory in vitest.ts sets MPO_VITEST_*
+ * to the same physical copies the aliases bind; this setup file (prepended
+ * onto every createVitestConfig setupFiles list) makes those requires land
+ * there. See MPO-37.
+ */
+const Module = require("module");
+const path = require("path");
+
+const reactDir = process.env.MPO_VITEST_REACT;
+const reactDomDir = process.env.MPO_VITEST_REACT_DOM;
+const schedulerDir = process.env.MPO_VITEST_SCHEDULER;
+
+if (reactDir && reactDomDir && !Module._mpoOneReact) {
+  Module._mpoOneReact = true;
+  const orig = Module._resolveFilename;
+  Module._resolveFilename = function pinned(request, parent, isMain, options) {
+    const next =
+      request === "react"
+        ? reactDir
+        : request.startsWith("react/")
+          ? path.join(reactDir, request.slice("react/".length))
+          : request === "react-dom"
+            ? reactDomDir
+            : request.startsWith("react-dom/")
+              ? path.join(reactDomDir, request.slice("react-dom/".length))
+              : request === "scheduler" && schedulerDir
+                ? schedulerDir
+                : null;
+    if (next) {
+      try {
+        return orig.call(this, next, parent, isMain, options);
+      } catch {
+        // package layout didn't match — keep Node's original lookup
+      }
+    }
+    return orig.call(this, request, parent, isMain, options);
+  };
+}

package/src/lint.spec.ts

@@ -0,0 +1,52 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveRoots, runConventionChecks } from "../lint.mjs";
+
+const fixtures: string[] = [];
+
+afterEach(() => {
+  for (const dir of fixtures.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeTree() {
+  const root = mkdtempSync(join(tmpdir(), "mpo-lint-"));
+  fixtures.push(root);
+  mkdirSync(join(root, "apps", "demo"), { recursive: true });
+  mkdirSync(join(root, "features", "demo"), { recursive: true });
+  writeFileSync(join(root, "apps", "demo", "App.tsx"), "export const App = () => null;\n");
+  return root;
+}
+
+describe("resolveRoots", () => {
+  it("defaults apps/features/public under root", () => {
+    const roots = resolveRoots({ root: "/tmp/app" });
+    expect(roots.apps).toBe(join("/tmp/app", "apps"));
+    expect(roots.features).toBe(join("/tmp/app", "features"));
+    expect(roots.public).toBe(join("/tmp/app", "public"));
+  });
+});
+
+describe("runConventionChecks", () => {
+  it("fails on a .css file under apps/", () => {
+    const root = makeTree();
+    writeFileSync(join(root, "apps", "demo", "bad.css"), "body { color: red; }\n");
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const code = runConventionChecks({ roots: { root } });
+    error.mockRestore();
+    expect(code).toBe(1);
+  });
+
+  it("passes a product app with a features twin and no css", () => {
+    const root = makeTree();
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const code = runConventionChecks({ roots: { root } });
+    log.mockRestore();
+    warn.mockRestore();
+    expect(code).toBe(0);
+  });
+});

package/src/oxlint.spec.ts

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import {
+  CHROME_PROPS,
+  LAYOUT_PROPS,
+  isPaletteModule,
+  matchColorLiteral,
+  plugin,
+} from "../oxlint.mjs";
+
+const pkg = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"),
+) as {
+  exports: Record<string, string | { import?: string; default?: string; types?: string }>;
+  files: string[];
+};
+
+describe("package exports", () => {
+  it("exports ./oxlint and ./lint and lists both in files", () => {
+    expect(pkg.exports["./oxlint"]).toBe("./oxlint.mjs");
+    const lintExport = pkg.exports["./lint"];
+    const lintPath = typeof lintExport === "string" ? lintExport : lintExport?.import;
+    expect(lintPath).toBe("./lint.mjs");
+    expect(pkg.files).toContain("oxlint.mjs");
+    expect(pkg.files).toContain("lint.mjs");
+  });
+});
+
+describe("matchColorLiteral", () => {
+  it("matches hex and functional CSS colours, not a Pokedex number in isolation of AST", () => {
+    expect(matchColorLiteral("#34c759")).toBe("#34c759");
+    expect(matchColorLiteral("#fff")).toBe("#fff");
+    expect(matchColorLiteral("rgba(0,0,0,0.35)")).toBe("rgba(0,0,0,0.35)");
+    expect(matchColorLiteral("hsl(0, 0%, 50%)")).toBe("hsl(0, 0%, 50%)");
+    expect(matchColorLiteral("$color10")).toBeUndefined();
+    expect(matchColorLiteral("#025")).toBe("#025");
+  });
+});
+
+describe("isPaletteModule", () => {
+  it("exempts themes/base, themes/accent, and *palette* files", () => {
+    expect(isPaletteModule("packages/themes/base.ts")).toBe(true);
+    expect(isPaletteModule("packages/themes/accent.ts")).toBe(true);
+    expect(isPaletteModule("src/brand-palette.ts")).toBe(true);
+    expect(isPaletteModule("features/console/src/conditions/ConditionsIndicator.tsx")).toBe(false);
+  });
+});
+
+describe("MPO-17 export surface", () => {
+  it("exposes chrome vs layout vocabularies and the oxlint plugin", () => {
+    expect(CHROME_PROPS).toContain("backgroundColor");
+    expect(CHROME_PROPS).toContain("bg");
+    expect(LAYOUT_PROPS).toContain("flex");
+    expect(plugin.meta?.name).toBe("mpo-conventions");
+    expect(plugin.rules?.["no-hex-literals"]).toBeDefined();
+    expect(plugin.rules?.["no-raw-typography"]).toBeDefined();
+    expect(plugin.rules?.["no-chrome-props"]).toBeUndefined();
+  });
+});

package/src/vitest.spec.ts

@@ -0,0 +1,151 @@
+/**
+ * createVitestConfig — resolve.extensions must never prefer a .test.* sibling,
+ * and dedupeReact aliases must bind one physical React (MPO-11 / MPO-37).
+ *
+ * Regression guard for MPO-11: the defaults listed ".test.ts" / ".test.tsx"
+ * first, so vite resolved an extensionless `import "./foo"` to foo.test.ts
+ * whenever both files existed. That pulled the test file's own imports into the
+ * module graph and killed the lookout unit job with "Cannot bundle Node.js
+ * built-in node:test imported from src/format.test.ts".
+ *
+ * Regression guard for MPO-37: aliasing react at the hoisted root directory
+ * while Vite realpath'd a package-local symlink put two copies in one graph.
+ * Render specs then died on `Cannot read properties of null (reading 'useEffect')`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { createServer, type ViteDevServer } from "vite";
+import { createVitestConfig } from "./vitest.js";
+
+const fixtureDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../tests/fixtures/extensionless-resolve",
+);
+
+const servers: ViteDevServer[] = [];
+
+afterAll(async () => {
+  await Promise.all(servers.map((server) => server.close()));
+});
+
+/**
+ * Resolve a specifier through a real vite pipeline built from the produced
+ * config, so the assertion exercises vite's own extension probing rather than
+ * re-implementing it.
+ */
+async function resolveThroughVite(specifier: string, importer: string) {
+  const config = createVitestConfig({ tamaguiConfig: false, dedupeReact: false });
+  const server = await createServer({
+    configFile: false,
+    logLevel: "silent",
+    root: fixtureDir,
+    server: { middlewareMode: true },
+    resolve: config.resolve,
+  });
+  servers.push(server);
+  const environment = server.environments?.client ?? server.environments?.ssr;
+  const container = environment ? environment.pluginContainer : (server as any).pluginContainer;
+  const resolved = await container.resolveId(specifier, importer);
+  return resolved?.id ?? null;
+}
+
+describe("resolve.extensions", () => {
+  it("does not list any .test.* extension", () => {
+    const extensions = createVitestConfig().resolve?.extensions ?? [];
+    expect(extensions.filter((extension) => extension.startsWith(".test."))).toEqual([]);
+  });
+
+  it("still resolves platform-specific and plain source extensions, web first", () => {
+    const extensions = createVitestConfig().resolve?.extensions ?? [];
+    expect(extensions).toEqual([
+      ".web.ts",
+      ".web.tsx",
+      ".web.js",
+      ".web.jsx",
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+    ]);
+    expect(extensions.indexOf(".web.ts")).toBeLessThan(extensions.indexOf(".ts"));
+  });
+
+  it("resolves an extensionless ./foo to foo.ts even when foo.test.ts sits beside it", async () => {
+    const id = await resolveThroughVite("./foo", path.join(fixtureDir, "entry.ts"));
+    expect(id).toBeTruthy();
+    expect(path.basename(id!)).toBe("foo.ts");
+    expect(id).not.toContain(".test.");
+  });
+});
+
+describe("dedupeReact aliases", () => {
+  const configDir = path.dirname(fileURLToPath(import.meta.url));
+  const componentsDir = path.resolve(configDir, "../../components");
+  const componentsReact = path.join(componentsDir, "node_modules/react");
+  const componentsReactDom = path.join(componentsDir, "node_modules/react-dom");
+
+  function aliasMap() {
+    return createVitestConfig({ tamaguiConfig: false }).resolve?.alias as Record<string, string>;
+  }
+
+  it("binds react-dom/client and jsx-runtime to the same physical copies as the packages", () => {
+    const aliases = aliasMap();
+    expect(aliases["react-dom/client"]).toBe(path.join(aliases["react-dom"], "client"));
+    expect(aliases["react-dom/server"]).toBe(path.join(aliases["react-dom"], "server"));
+    expect(aliases["react/jsx-runtime"]).toBe(path.join(aliases.react, "jsx-runtime"));
+    expect(aliases["react/jsx-dev-runtime"]).toBe(path.join(aliases.react, "jsx-dev-runtime"));
+    expect(aliases.react).not.toBe(aliases["react-dom"]);
+  });
+
+  it("canonicalizes each alias through realpath so Vite cannot see two copies", () => {
+    const aliases = aliasMap();
+    for (const pkg of ["react", "react-dom", "scheduler"] as const) {
+      expect(fs.existsSync(aliases[pkg])).toBe(true);
+      expect(aliases[pkg]).toBe(fs.realpathSync(aliases[pkg]));
+    }
+  });
+
+  it.skipIf(!fs.existsSync(componentsReact) || !fs.existsSync(componentsReactDom))(
+    "prefers the package-under-test physical copy over the hoisted root",
+    () => {
+      const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(componentsDir);
+      try {
+        const aliases = aliasMap();
+        expect(aliases.react).toBe(fs.realpathSync(componentsReact));
+        expect(aliases["react-dom"]).toBe(fs.realpathSync(componentsReactDom));
+      } finally {
+        cwdSpy.mockRestore();
+      }
+    },
+  );
+
+  it("does not also dedupe react to the hoisted root copy", () => {
+    const dedupe = createVitestConfig({ tamaguiConfig: false }).resolve?.dedupe ?? [];
+    expect(dedupe).not.toContain("react");
+    expect(dedupe).not.toContain("react-dom");
+  });
+
+  it("inlines the CJS react deps that Node would otherwise require from the hoisted root", () => {
+    const config = createVitestConfig({ tamaguiConfig: false }) as {
+      test?: { server?: { deps?: { inline?: unknown[]; external?: unknown[] } } };
+    };
+    const inline = config.test?.server?.deps?.inline ?? [];
+    expect(
+      inline.some((entry) => entry instanceof RegExp && String(entry).includes("@tanstack")),
+    ).toBe(true);
+    expect(inline).toContain("use-sync-external-store");
+  });
+
+  it("installs a worker setup that pins CJS require('react') to the same copy", () => {
+    const config = createVitestConfig({ tamaguiConfig: false }) as {
+      test?: { setupFiles?: string[]; server?: { deps?: { external?: unknown[] } } };
+    };
+    const files = config.test?.setupFiles ?? [];
+    expect(files.some((file) => file.endsWith("pin-react-require.cjs"))).toBe(true);
+    const external = config.test?.server?.deps?.external ?? [];
+    expect(external.some((entry) => String(entry).endsWith("pin-react-require.cjs"))).toBe(true);
+  });
+});