@multiplatform.one/config 7.4.0 → 7.5.0

package/lint.mjs

@@ -0,0 +1,778 @@
+#!/usr/bin/env node
+/**
+ * Structural convention checks that oxlint cannot express as file lints.
+ *
+ * 1. Fail on `.css` files under apps/* (vendor/bench trees ignored)
+ * 2. Fail if apps/<name> lacks features/<name> (tooling shells exempt)
+ * 3. Fail on SILENT NO-OP TOKENS — a string literal handed to a design-system
+ *    prop that names nothing in the corresponding registry. Tamagui does not
+ *    type-check these (the workspace only augments `TamaguiCustomConfig` with
+ *    shorthands, so theme/token names stay open strings) and it does not throw
+ *    or warn at the call site either: `getTokenForKey` returns `undefined` and
+ *    the prop is dropped, so the styling simply never happens. Each check
+ *    reads its vocabulary from the registry's own source so it cannot drift.
+ * 4. Fail on SIZE-RECIPE ESCAPE (LC-65) — JSX numeric literals that set
+ *    control chrome by hand (`height={N}`, `minHeight={N}`,
+ *    `paddingHorizontal={N}`, `fontSize={N}`). Identifiers
+ *    (`MIN_PRESS_TARGET`, `pressTargetHitSlop`, `recipe.height`,
+ *    `knobProps.control.height`) are fine. Escape with `sizeRecipeEscape` or
+ *    `size-recipe-escape:` on the previous line or same statement. Pilot:
+ *    Button/, InputParts/, fields/Select/ only.
+ *
+ * Usage:
+ *   import { runConventionChecks } from "@multiplatform.one/config/lint";
+ *   runConventionChecks({ roots: { root, apps, features, public } });
+ *
+ * CLI: node lint.mjs   (roots default to process.cwd())
+ * Exit 1 on any violation.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * @typedef {{ root?: string, apps?: string, features?: string, public?: string }} ConventionRoots
+ * @typedef {{ roots?: ConventionRoots }} RunConventionChecksOptions
+ */
+
+/** @type {string} */
+let ROOT = process.cwd();
+/** @type {string} */
+let APPS_DIR = join(ROOT, "apps");
+/** @type {string} */
+let FEATURES_DIR = join(ROOT, "features");
+/** @type {string} */
+let PUBLIC_DIR = join(ROOT, "public");
+
+/**
+ * @param {ConventionRoots} [roots]
+ */
+export function resolveRoots(roots = {}) {
+  const root = roots.root ?? process.cwd();
+  return {
+    root,
+    apps: roots.apps ?? join(root, "apps"),
+    features: roots.features ?? join(root, "features"),
+    public: roots.public ?? join(root, "public"),
+  };
+}
+
+/**
+ * @param {ConventionRoots} [roots]
+ */
+function applyRoots(roots) {
+  const resolved = resolveRoots(roots);
+  ROOT = resolved.root;
+  APPS_DIR = resolved.apps;
+  FEATURES_DIR = resolved.features;
+  PUBLIC_DIR = resolved.public;
+  sourceFileCache = undefined;
+  requireFromRoot = createRequire(join(ROOT, "package.json"));
+}
+
+/** Shared platform / docs / chain shells — not product apps from
+ *  mpo init --app. Extension targets (vscode, webext) are no longer shells:
+ *  they live INSIDE the product app (apps/<name>/vscode, apps/<name>/webext)
+ *  alongside the gnome/tauri targets. */
+const FEATURES_TWIN_EXEMPT = new Set([
+  "frappe",
+  "keycloak",
+  "storybook",
+  "storybook-expo",
+  "uxpin",
+  "vocs",
+  "ethereum",
+  "solana",
+  "sui",
+]);
+
+const CSS_IGNORE_DIR_NAMES = new Set([
+  "node_modules",
+  "dist",
+  ".dist",
+  ".tamagui",
+  "build",
+  "coverage",
+  "env", // frappe bench python env
+  "sites",
+  "logs",
+  "storybook-static", // storybook build output
+  "playwright-report", // playwright html report (regenerated per e2e run)
+  "test-results", // playwright traces/attachments
+]);
+
+/** Build-output dirs are prefix-matched so variants like dist-spa-e2e are covered. */
+const CSS_IGNORE_DIR_PREFIXES = ["dist-", "dist_"];
+
+/** Path prefixes under apps/ that are never scanned for .css */
+const CSS_IGNORE_PREFIXES = [
+  join("frappe", "apps"), // upstream frappe apps tree
+  join("frappe", "env"),
+  join("frappe", "sites"),
+  // Keycloakify vendored theme resources (not app-authored styles)
+  join("keycloak", "public", "keycloakify-dev-resources"),
+  // Platform-forced: vscode webviews rewrite <link href> to vscode-resource
+  // URIs and url() resolves relative to the emitted stylesheet — inline
+  // <style> would resolve against vscode-webview:// instead (LC-33 fonts).
+  join("one", "vscode", "webview", "fonts.css"),
+];
+
+/** Generated Tamagui CSS extract filenames (not hand-authored app styles). */
+const GENERATED_CSS_NAMES = new Set(["tamagui.css", "tamagui.content.css"]);
+
+/**
+ * @param {string} dir
+ * @param {(filePath: string) => void} onFile
+ */
+function walkFiles(dir, onFile) {
+  if (!existsSync(dir)) return;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") && entry.name !== ".storybook") {
+      // skip VCS / cache dirs; allow .storybook
+      if (entry.isDirectory()) continue;
+    }
+    if (CSS_IGNORE_DIR_NAMES.has(entry.name)) continue;
+    if (
+      entry.isDirectory() &&
+      CSS_IGNORE_DIR_PREFIXES.some((prefix) => entry.name.startsWith(prefix))
+    ) {
+      continue;
+    }
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(full, onFile);
+    } else if (entry.isFile()) {
+      onFile(full);
+    }
+  }
+}
+
+function isCssIgnored(absPath) {
+  const rel = relative(APPS_DIR, absPath);
+  if (CSS_IGNORE_PREFIXES.some((prefix) => rel === prefix || rel.startsWith(prefix + "/"))) {
+    return true;
+  }
+  const base = rel.split(/[/\\]/).pop() ?? "";
+  return GENERATED_CSS_NAMES.has(base);
+}
+
+function listAppNames() {
+  if (!existsSync(APPS_DIR)) return [];
+  return readdirSync(APPS_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith(".") && d.name !== "node_modules")
+    .map((d) => d.name)
+    .sort();
+}
+
+function checkCssInApps() {
+  /** @type {string[]} */
+  const violations = [];
+  if (!existsSync(APPS_DIR)) return violations;
+
+  walkFiles(APPS_DIR, (filePath) => {
+    if (!filePath.endsWith(".css")) return;
+    if (isCssIgnored(filePath)) return;
+    violations.push(relative(ROOT, filePath));
+  });
+  return violations;
+}
+
+// ── Silent no-op token registries ─────────────────────────────────────────
+
+/** Bound to the consumer root so SHC/Lookout resolve their own Tamagui copies. */
+let requireFromRoot = createRequire(join(process.cwd(), "package.json"));
+
+/**
+ * Resolve a registry package. A package that cannot be resolved disables its
+ * check (reported by `runConventionChecks`) instead of crashing the run — a
+ * fresh clone with a partial install must still get the structural checks.
+ * @param {string} name
+ */
+function tryRequire(name) {
+  try {
+    return requireFromRoot(name);
+  } catch {
+    return undefined;
+  }
+}
+
+/** @param {string} relPath */
+function readPublicSource(relPath) {
+  const full = join(PUBLIC_DIR, relPath);
+  return existsSync(full) ? readFileSync(full, "utf8") : "";
+}
+
+/**
+ * Body of an object/interface literal that starts at `marker`, from its first
+ * `{` to the first line-anchored closing brace. Used to read a registry's keys
+ * out of the source that declares them.
+ * @param {string} src
+ * @param {string} marker
+ * @param {string} end
+ */
+function sliceBlock(src, marker, end) {
+  const start = src.indexOf(marker);
+  if (start === -1) return "";
+  const open = src.indexOf("{", start);
+  if (open === -1) return "";
+  const close = src.indexOf(end, open);
+  return close === -1 ? "" : src.slice(open, close);
+}
+
+/**
+ * Top-level keys declared in an object/interface literal body. Numeric keys
+ * count — scale registries like the font-size table are keyed `1:`…`16:`.
+ * @param {string} body
+ * @param {number} indent
+ */
+function keysOfBlock(body, indent) {
+  /** @type {string[]} */
+  const keys = [];
+  const re = new RegExp(`^ {${indent}}([A-Za-z0-9][A-Za-z0-9]*)\\s*:`, "gm");
+  for (const m of body.matchAll(re)) keys.push(m[1]);
+  return keys;
+}
+
+/** Source files every token check scans, read once and shared. */
+let sourceFileCache;
+function sourceFiles() {
+  if (sourceFileCache) return sourceFileCache;
+  /** @type {{ rel: string, src: string }[]} */
+  const files = [];
+  const collect = (filePath) => {
+    if (!/\.(tsx|ts|jsx|js)$/.test(filePath)) return;
+    if (/\.(spec|test)\./.test(filePath)) return;
+    files.push({ rel: relative(ROOT, filePath), src: readFileSync(filePath, "utf8") });
+  };
+  for (const dir of [PUBLIC_DIR, APPS_DIR, FEATURES_DIR]) walkFiles(dir, collect);
+  sourceFileCache = files;
+  return files;
+}
+
+/**
+ * 1-based line of a match offset.
+ * @param {string} src
+ * @param {number} index
+ */
+function lineAt(src, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (src.charCodeAt(i) === 10) line += 1;
+  return line;
+}
+
+/**
+ * Run one prop-literal regex over every scanned file.
+ * @param {RegExp} re
+ * @param {(match: RegExpMatchArray) => string | undefined} check returns the violation text, or undefined when valid
+ */
+function scanLiterals(re, check) {
+  /** @type {string[]} */
+  const violations = [];
+  for (const { rel, src } of sourceFiles()) {
+    for (const m of src.matchAll(re)) {
+      const message = check(m);
+      if (message) violations.push(`${rel}:${lineAt(src, m.index ?? 0)} — ${message}`);
+    }
+  }
+  return violations;
+}
+
+/**
+ * The animation vocabulary is a CLOSED set (css.ts / reactNative.ts register
+ * exactly these keys). A `transition="X"` with an X outside the set is not a
+ * type error — Tamagui silently ignores the unknown animation name, so the
+ * element renders with NO animation. That is invisible until someone notices
+ * "this doesn't animate" (e.g. DatePicker's `transition="quicker"` typo, which
+ * killed the selected-date enter animation across all five pickers). Read the
+ * registry from source so this check can never drift from the tokens.
+ * @returns {Set<string>}
+ */
+function readAnimationTokens() {
+  const tokens = new Set(["none"]); // valid non-animating value
+  const src = readPublicSource("theme/src/theme/animations/css.ts");
+  if (!src) return tokens;
+  for (const key of keysOfBlock(sliceBlock(src, "animationConfig =", "} as const"), 2)) {
+    tokens.add(key);
+  }
+  return tokens;
+}
+
+/** Flag `transition="literal"` / `transition={"literal"}` using an unregistered token. */
+function checkTransitionTokens() {
+  const valid = readAnimationTokens();
+  // Only string LITERALS directly on the prop — dynamic values (variables,
+  // ternaries, knobProps.transition) resolve at runtime and are out of scope.
+  const re = /\btransition=(?:"([a-zA-Z0-9]+)"|\{\s*"([a-zA-Z0-9]+)"\s*\})/g;
+  const violations = scanLiterals(re, (m) => {
+    const token = m[1] ?? m[2];
+    return valid.has(token) ? undefined : `transition="${token}"`;
+  });
+  return { violations, valid: [...valid].filter((t) => t !== "none").sort() };
+}
+
+/**
+ * Every registered Tamagui theme name, plus each sub-theme SEGMENT a `theme`
+ * prop may name on its own (`theme="accent"` selects `light_accent` under the
+ * light scheme). Rebuilt from the same three sources `createThemesBuilder`
+ * composes: the theme-builder's generated names for this base/children/accent
+ * shape, the stock `@tamagui/themes` names, and the gray aliases declared in
+ * createThemes.ts. Palettes are irrelevant here — only the NAMES are.
+ * @returns {Set<string>}
+ */
+function readThemeNames() {
+  /** @type {Set<string>} */
+  const names = new Set();
+  const builder = tryRequire("@tamagui/theme-builder");
+  const stock = tryRequire("@tamagui/themes");
+  const src = readPublicSource("theme/src/theme/createThemes.ts");
+  if (!builder?.createThemes || !stock?.themes || !src) return names;
+  const ramp = Array.from({ length: 14 }, (_, i) => `hsl(0, 0%, ${i * 7}%)`);
+  const palette = { palette: { dark: ramp, light: ramp } };
+  /** @type {Record<string, unknown>} */
+  const childrenThemes = {};
+  for (const key of keysOfBlock(sliceBlock(src, "const childrenThemes =", "\n  };"), 4)) {
+    childrenThemes[key] = palette;
+  }
+  try {
+    for (const name of Object.keys(
+      builder.createThemes({ base: palette, childrenThemes, accent: palette }),
+    )) {
+      names.add(name);
+    }
+  } catch {
+    return new Set();
+  }
+  for (const name of Object.keys(stock.themes)) names.add(name);
+  for (const m of sliceBlock(src, "const grayTheme =", "\n};").matchAll(
+    /^ {2}([a-zA-Z][a-zA-Z0-9_]*)\s*:/gm,
+  )) {
+    names.add(m[1]);
+  }
+  /** @type {string[]} */
+  const segments = [];
+  for (const name of names) for (const part of name.split("_").slice(1)) segments.push(part);
+  for (const segment of segments) names.add(segment);
+  return names;
+}
+
+/**
+ * Every key resolvable as `$value` on a color-bearing prop, composed exactly
+ * the way `createThemesBuilder` composes the live themes: the structural keys
+ * the theme-builder generates (colorN / background0N / accentN / …), the stock
+ * base themes, the Radix ramps createThemes.ts splats into `extra`, the shadow
+ * slots, and the project's semantic aliases from `getBaseTheme`.
+ * @returns {Set<string>}
+ */
+function readThemeKeys() {
+  /** @type {Set<string>} */
+  const keys = new Set();
+  const builder = tryRequire("@tamagui/theme-builder");
+  const stock = tryRequire("@tamagui/themes");
+  const colors = tryRequire("@tamagui/colors");
+  const src = readPublicSource("theme/src/theme/createThemes.ts");
+  const builderSrc = readPublicSource("theme/src/theme/defaults/builderOptions.ts");
+  if (!builder?.createThemes || !stock?.themes || !colors || !src || !builderSrc) return keys;
+  const ramp = Array.from({ length: 14 }, (_, i) => `hsl(0, 0%, ${i * 7}%)`);
+  const palette = { palette: { dark: ramp, light: ramp } };
+  try {
+    const generated = builder.createThemes({
+      base: palette,
+      childrenThemes: { warning: palette },
+      accent: palette,
+    });
+    for (const theme of Object.values(generated)) for (const k of Object.keys(theme)) keys.add(k);
+  } catch {
+    return new Set();
+  }
+  for (const name of ["light", "dark"]) {
+    for (const k of Object.keys(stock.themes[name] ?? {})) keys.add(k);
+  }
+  for (const m of src.matchAll(/\.\.\.Colors\.([A-Za-z0-9]+)\s*,/g)) {
+    for (const k of Object.keys(colors[m[1]] ?? {})) keys.add(k);
+  }
+  for (const k of keysOfBlock(sliceBlock(src, "export interface Shadows", "\n}"), 2)) keys.add(k);
+  keys.add("shadowColor");
+  for (const k of keysOfBlock(sliceBlock(builderSrc, "function getBaseTheme", "\n}"), 4))
+    keys.add(k);
+  return keys;
+}
+
+/** Font-size steps the house fonts register (`defaults/fonts.ts`). */
+function readFontSizeSteps() {
+  /** @type {Set<string>} */
+  const steps = new Set();
+  const src = readPublicSource("theme/src/theme/defaults/fonts.ts");
+  if (!src) return steps;
+  for (const k of keysOfBlock(sliceBlock(src, "const interBaseSizes", "\n};"), 2)) steps.add(k);
+  return steps;
+}
+
+/**
+ * Flag a `$token` style literal that resolves to NOTHING.
+ *
+ * `getTokenForKey` looks a `$value` up in the active theme, then in the token
+ * scale its prop belongs to (`tokenCategories`), then in `tokens.space` as a
+ * universal fallback — and when all three miss it returns `undefined`, so the
+ * prop is dropped from the style entirely. The only signal is a one-time,
+ * collapsed dev console group that names neither the file nor the component
+ * and which Tamagui itself documents as "sometimes harmless", so in practice
+ * an unregistered token is invisible (e.g. `color="$colorSubtle"` in
+ * GeolocationMap.native, a token no theme ever defined).
+ *
+ * Font props are the one exception to the space fallback: `fontSize` resolves
+ * against the active font's own size scale and, on a miss, passes the RAW
+ * "$n" string through as a CSS length — equally silent, equally dead.
+ */
+function checkStyleTokens() {
+  const helpers = tryRequire("@tamagui/helpers");
+  const themesPkg = tryRequire("@tamagui/themes");
+  const shorthandsPkg = tryRequire("@tamagui/shorthands");
+  const themeKeys = readThemeKeys();
+  const fontSizeSteps = readFontSizeSteps();
+  if (!helpers?.tokenCategories || !themesPkg?.tokens || !themeKeys.size || !fontSizeSteps.size) {
+    return { violations: [], ok: false };
+  }
+  const tokens = themesPkg.tokens;
+  const spaceScale = new Set(Object.keys(tokens.space ?? {}));
+  /** @type {Map<string, Set<string>>} prop → every `$value` that resolves */
+  const byProp = new Map();
+  // Props with a scale of their own (radius / size / zIndex / color).
+  for (const [category, props] of Object.entries(helpers.tokenCategories)) {
+    const resolvable = new Set([
+      ...themeKeys,
+      ...Object.keys(tokens[category] ?? {}),
+      ...spaceScale,
+    ]);
+    for (const prop of Object.keys(props)) byProp.set(prop, resolvable);
+  }
+  // Every other view style prop lands on the space fallback (padding, margin,
+  // gap, inset, border widths, …) — the biggest surface by call-site count.
+  const spaceResolvable = new Set([...themeKeys, ...spaceScale]);
+  for (const prop of Object.keys(helpers.stylePropsAll ?? {})) {
+    if (byProp.has(prop)) continue;
+    if (helpers.stylePropsTextOnly?.[prop]) continue;
+    if (helpers.stylePropsTransform?.[prop]) continue;
+    if (helpers.stylePropsUnitless?.[prop]) continue;
+    byProp.set(prop, spaceResolvable);
+  }
+  byProp.set("fontSize", new Set([...themeKeys, ...fontSizeSteps]));
+  // Shorthands are the same prop by another name (`bg`, `br`, `fos`, …).
+  for (const [short, long] of Object.entries(shorthandsPkg?.shorthands ?? {})) {
+    const resolvable = byProp.get(long);
+    if (resolvable) byProp.set(short, resolvable);
+  }
+  const props = [...byProp.keys()].sort((a, b) => b.length - a.length).join("|");
+  const re = new RegExp(
+    `\\b(${props})=(?:"\\$([A-Za-z0-9]+)"|\\{\\s*"\\$([A-Za-z0-9]+)"\\s*\\})`,
+    "g",
+  );
+  const violations = scanLiterals(re, (m) => {
+    const token = m[2] ?? m[3];
+    return byProp.get(m[1])?.has(token) ? undefined : `${m[1]}="$${token}"`;
+  });
+  return { violations, ok: true };
+}
+
+/** Flag `theme="literal"` naming a theme that was never built. */
+function checkThemeNames() {
+  const valid = readThemeNames();
+  if (!valid.size) return { violations: [], ok: false };
+  const re = /\btheme=(?:"([A-Za-z][A-Za-z0-9_]*)"|\{\s*"([A-Za-z][A-Za-z0-9_]*)"\s*\})/g;
+  const violations = scanLiterals(re, (m) => {
+    const name = m[1] ?? m[2];
+    return valid.has(name) ? undefined : `theme="${name}"`;
+  });
+  return { violations, ok: true };
+}
+
+/** Intent names registered in `defaultIntents`. */
+function readIntentNames() {
+  /** @type {Set<string>} */
+  const names = new Set();
+  const src = readPublicSource("theme/src/theme/intents.ts");
+  if (!src) return names;
+  for (const m of sliceBlock(src, "export const defaultIntents", "\n};").matchAll(
+    /^ {2}([a-zA-Z][a-zA-Z0-9]*)\s*:\s*\{/gm,
+  )) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+/**
+ * Flag `useResolvedKnobs({ intent: "literal" })` naming an unregistered intent.
+ * `UseResolvedKnobsOptions.intent` is a plain `string` (component-level intent
+ * props are typed unions, this one is the open seam), and an unknown name just
+ * misses `defaultIntents[intent]` — no overrides merge, so the component keeps
+ * its base knobs and renders exactly as if no intent had been passed.
+ */
+function checkIntentTokens() {
+  const valid = readIntentNames();
+  if (!valid.size) return { violations: [], valid: [], ok: false };
+  const call = /useResolvedKnobs\(/g;
+  const intentArg = /\bintent:\s*"([A-Za-z0-9]+)"/g;
+  /** @type {string[]} */
+  const violations = [];
+  for (const { rel, src } of sourceFiles()) {
+    for (const m of src.matchAll(call)) {
+      // Options object only — stop at the call's own closing paren.
+      let depth = 0;
+      let end = (m.index ?? 0) + m[0].length - 1;
+      for (; end < src.length; end++) {
+        const c = src[end];
+        if (c === "(") depth += 1;
+        else if (c === ")") {
+          depth -= 1;
+          if (depth === 0) break;
+        }
+      }
+      const args = src.slice((m.index ?? 0) + m[0].length, end);
+      for (const arg of args.matchAll(intentArg)) {
+        if (!valid.has(arg[1])) {
+          violations.push(`${rel}:${lineAt(src, m.index ?? 0)} — intent: "${arg[1]}"`);
+        }
+      }
+    }
+  }
+  return { violations, valid: [...valid].sort(), ok: true };
+}
+
+/**
+ * Two more silent-animation-death shapes, both found dead in the live sweep
+ * (`p-results/fix-animation-sweep.md`) and neither catchable by the token
+ * guard above, because the token is valid — it is the PROP that is wrong.
+ *
+ * 1. `animation` is the tamagui 1.x spelling. On 2.x the prop is `transition`
+ *    and `animation` is NOT an alias, so it is dropped and the node sits at
+ *    `transition-duration: 0s`. It hides in two spellings: the JSX attribute,
+ *    and an `animation:` key inside a conditional spread.
+ * 2. LC-24: `enterStyle`/`exitStyle` with no transition driver on the same
+ *    element is dead code — the styles are declared and never interpolated
+ *    (raw tamagui Popover/Dialog Content bypassing the house wrappers).
+ */
+function checkAnimationProps() {
+  /** @type {string[]} */
+  const legacyProp = [];
+  /** @type {string[]} */
+  const driverless = [];
+  const scan = (filePath) => {
+    if (!/\.(tsx|jsx)$/.test(filePath)) return;
+    if (/\.(spec|test|stories)\./.test(filePath)) return;
+    const src = readFileSync(filePath, "utf8");
+    const rel = relative(ROOT, filePath);
+    // Any `…transition`-valued animation key, so prefixed spellings like
+    // `ctx.knobProps.transition` are caught too. Deliberately NOT "any value":
+    // that also matches TS annotations (`animation: any`), css-in-js, and
+    // unrelated config objects that have nothing to do with the tamagui prop.
+    for (const m of src.matchAll(/\banimation=\{|\banimation:\s*[\w$.[\]?]*\btransition\b/g)) {
+      const line = src.slice(0, m.index).split("\n").length;
+      legacyProp.push(`${rel}:${line} — \`${m[0]}\` (tamagui 1.x prop; use \`transition\`)`);
+    }
+    // Element-scoped: an enter/exitStyle needs a transition on the SAME tag.
+    // `=>` is allowed through: a `>` inside an arrow-function prop otherwise
+    // truncates the tag and hides everything after it from this check.
+    for (const tag of src.matchAll(/<[A-Z][\w.]*(?:\s(?:=>|[^>])*)?>/gs)) {
+      const t = tag[0];
+      if (!/\b(enterStyle|exitStyle)=/.test(t)) continue;
+      if (/\btransition[=:]/.test(t)) continue;
+      const line = src.slice(0, tag.index).split("\n").length;
+      driverless.push(`${rel}:${line} — enter/exitStyle with no \`transition\` driver (LC-24)`);
+    }
+  };
+  for (const dir of [PUBLIC_DIR, APPS_DIR, FEATURES_DIR]) walkFiles(dir, scan);
+  return { legacyProp, driverless };
+}
+
+function checkFeaturesTwins() {
+  /** @type {string[]} */
+  const violations = [];
+  for (const name of listAppNames()) {
+    if (FEATURES_TWIN_EXEMPT.has(name)) continue;
+    const twin = join(FEATURES_DIR, name);
+    if (!existsSync(twin) || !statSync(twin).isDirectory()) {
+      violations.push(`apps/${name} lacks features/${name} (app ↔ features twin required)`);
+    }
+  }
+  return violations;
+}
+
+/**
+ * LC-65 SIZE-RECIPE ESCAPE — numeric JSX literals that paint control chrome
+ * by hand, bypassing the size recipe. Pilot is narrow on purpose: only
+ * Button/, InputParts/, and fields/Select/ under public/forms/src. Widen
+ * the prefix list when the rest of the catalog migrates.
+ *
+ * Flagged: height={N} / minHeight={N} / paddingHorizontal={N} / fontSize={N}
+ * where N is a number. Token strings (`"$4"`) and identifiers
+ * (`MIN_PRESS_TARGET`, `recipe.height`, `knobProps.control.height`) do not
+ * match. Escape: `sizeRecipeEscape` or `size-recipe-escape:` on the previous
+ * line or in the same statement (the prop, including a multiline `{…}`).
+ */
+function checkSizeRecipeEscape() {
+  const formsSrc = join(PUBLIC_DIR, "forms", "src");
+  const pilotPrefixes = [
+    "public/forms/src/Button/",
+    "public/forms/src/InputParts/",
+    "public/forms/src/fields/Select/",
+    // Migrated onto generated recipe families 2026-08-14 (catalog wave):
+    "public/forms/src/Chip/",
+    "public/forms/src/Skeleton/",
+    "public/forms/src/fields/PhoneInput/",
+    "public/forms/src/fields/SearchInput/",
+    "public/forms/src/fields/Slider/",
+    "public/forms/src/fields/Stepper/",
+    "public/forms/src/fields/Switch/",
+  ];
+  const re = /\b(height|minHeight|paddingHorizontal|fontSize)=\{\s*(-?\d+(?:\.\d+)?)\s*\}/g;
+  /** @type {string[]} */
+  const violations = [];
+  walkFiles(formsSrc, (filePath) => {
+    if (!/\.(tsx|ts)$/.test(filePath)) return;
+    const rel = relative(ROOT, filePath);
+    if (/\.(spec|stories)\./.test(rel)) return;
+    if (rel.includes("__snapshots__")) return;
+    if (!pilotPrefixes.some((prefix) => rel.startsWith(prefix))) return;
+    const src = readFileSync(filePath, "utf8");
+    const lines = src.split("\n");
+    for (const m of src.matchAll(re)) {
+      const line = lineAt(src, m.index ?? 0);
+      const current = lines[line - 1] ?? "";
+      const trimmed = current.trim();
+      if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+        continue;
+      }
+      const previous = lines[line - 2] ?? "";
+      const window = `${previous}\n${current}\n${m[0]}`;
+      if (/sizeRecipeEscape|size-recipe-escape:/.test(window)) continue;
+      violations.push(`${rel}:${line} — ${m[1]}={${m[2]}}`);
+    }
+  });
+  return violations;
+}
+
+/**
+ * Run structural convention checks over a consumer tree.
+ *
+ * @param {RunConventionChecksOptions} [options]
+ * @returns {number} 0 when clean, 1 when any check failed
+ */
+export function runConventionChecks(options = {}) {
+  applyRoots(options.roots);
+  const css = checkCssInApps();
+  const twins = checkFeaturesTwins();
+  const sizeRecipeEscape = checkSizeRecipeEscape();
+  const tokens = checkTransitionTokens();
+  const styleTokens = checkStyleTokens();
+  const themeNames = checkThemeNames();
+  const intents = checkIntentTokens();
+  const animProps = checkAnimationProps();
+  let failed = false;
+
+  if (animProps.legacyProp.length) {
+    failed = true;
+    console.error(
+      "Convention: `animation` is the tamagui 1.x prop — on 2.x it is silently dropped (no animation at all). Use `transition`.\n",
+    );
+    for (const msg of animProps.legacyProp) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (animProps.driverless.length) {
+    failed = true;
+    console.error(
+      "Convention (LC-24): enterStyle/exitStyle without a `transition` on the same element never interpolates — the styles are dead code.\n",
+    );
+    for (const msg of animProps.driverless) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (css.length) {
+    failed = true;
+    console.error("Convention: .css files are banned under apps/*\n");
+    for (const file of css) console.error(`  ${file}`);
+    console.error("");
+  }
+
+  if (twins.length) {
+    failed = true;
+    console.error("Convention: each product app must have a features/<name> twin\n");
+    for (const msg of twins) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (sizeRecipeEscape.length) {
+    failed = true;
+    console.error(
+      "Convention (LC-65 SIZE-RECIPE ESCAPE): control chrome (height / minHeight / paddingHorizontal / fontSize) must come from the size recipe, not a numeric literal. Escape with `sizeRecipeEscape` or `// size-recipe-escape:` on the previous line or same statement. Pilot: Button/, InputParts/, fields/Select/.\n",
+    );
+    for (const msg of sizeRecipeEscape) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (tokens.violations.length) {
+    failed = true;
+    console.error(
+      `Convention: transition="…" must use a registered animation token (${tokens.valid.join(", ")}, or "none"). An unknown token silently disables the animation.\n`,
+    );
+    for (const msg of tokens.violations) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (styleTokens.violations.length) {
+    failed = true;
+    console.error(
+      "Convention: a `$token` style literal must resolve — as a theme key ($color11, $borderColor, $accentBackground, a Radix ramp step), as a token in the prop's own scale (radius/size/zIndex/color), or as a space token. None of those matched, so Tamagui drops the prop and the style never applies.\n",
+    );
+    for (const msg of styleTokens.violations) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (themeNames.violations.length) {
+    failed = true;
+    console.error(
+      'Convention: theme="…" must name a built theme or sub-theme (a scheme like light/dark, a hue like blue/red/green, a semantic child like error/warning/success, accent, or a state like active/alt1/alt2). An unbuilt name silently inherits the PARENT theme, so the element renders untinted.\n',
+    );
+    for (const msg of themeNames.violations) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (intents.violations.length) {
+    failed = true;
+    console.error(
+      `Convention: useResolvedKnobs({ intent }) must name a registered intent (${intents.valid.join(", ")}). An unknown name merges no overrides, so the component silently renders with its base knobs.\n`,
+    );
+    for (const msg of intents.violations) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  for (const [name, ok] of [
+    ["style token", styleTokens.ok],
+    ["theme name", themeNames.ok],
+    ["intent", intents.ok],
+  ]) {
+    if (!ok) {
+      console.warn(
+        `lint-conventions: skipped the ${name} check — its registry could not be read (incomplete install?).`,
+      );
+    }
+  }
+
+  if (failed) {
+    console.error(
+      "See AGENTS.md (package boundaries / import rules). Structural checks: @multiplatform.one/config/lint",
+    );
+    return 1;
+  }
+
+  console.log("lint-conventions: ok");
+  return 0;
+}
+
+const invokedDirectly =
+  typeof process.argv[1] === "string" && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  process.exit(runConventionChecks());
+}