@multiplatform.one/config 7.10.0 → 7.15.0

package/oxlint.mjs

@@ -9,7 +9,10 @@
  *   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.
+ *     the deliverable. So is a file with a `// hex-escape: <reason>`
+ *     comment, a surface no theme token reaches; lint.mjs fails the comment
+ *     unless the spec's `## Colour-literal escapes` table has that file and
+ *     reason (MPO-326).
  *   mpo-conventions/no-raw-typography — AN-8: app text never rides raw
  *     Tamagui*-prefixed typography escape hatches (TamaguiText, TamaguiHeading,
  *     TamaguiH1…, TamaguiParagraph, TamaguiSizableText, TamaguiAnchor) outside
@@ -23,9 +26,15 @@
  *     on those same imports. Silent behind sizeRecipeEscape() and inside a
  *     file listed as DRAWING. An undeclared `// mpo-drawing` pragma is a
  *     lint.mjs failure, not a skip here.
+ *   mpo-conventions/no-child-margin — `00` L9a: the parent owns the gap. Ban a
+ *     non-zero margin* prop on any element nested inside another element's
+ *     JSX. The outermost element of a tree is left alone (a file cannot see
+ *     whether its root is a screen's), and element names the spec's
+ *     `## Slot margins` SLOT-MARGIN row lists are the declared slots (MPO-23).
  */
 
 import { isDrawingFile, readDrawingRegistry } from "./drawing-registry.mjs";
+import { readSlotMarginRegistry } from "./spec-registry.mjs";
 
 /** Hex + functional CSS colour literals. AST-visited only (not a text scan). */
 export const COLOR_LITERAL =
@@ -35,6 +44,41 @@ export const COLOR_LITERAL =
 export const PALETTE_FILE =
   /(?:^|\/)themes\/(base|accent)\.(tsx?|jsx?)$|(?:^|\/)[^/]*palette[^/]*\.(tsx?|jsx?)$/i;
 
+/**
+ * A `hex-escape: <reason>` line or block comment. A JSDoc `*` line or a
+ * backticked mention is prose about the marker, not the marker.
+ */
+const HEX_ESCAPE_COMMENT = /(?<!`)(?:\/\/|\/\*)\s*hex-escape:\s*(.*?)\s*(?:\*\/.*)?$/;
+
+/**
+ * Every `hex-escape:` comment in a source file, with the reason it writes.
+ * @param {string} src
+ * @returns {{ line: number, reason: string }[]}
+ */
+export function findHexEscapes(src) {
+  if (!src.includes("hex-escape:")) return [];
+  /** @type {{ line: number, reason: string }[]} */
+  const sites = [];
+  src.split("\n").forEach((text, index) => {
+    if (text.trim().startsWith("*")) return;
+    const match = text.match(HEX_ESCAPE_COMMENT);
+    if (match) sites.push({ line: index + 1, reason: match[1].trim() });
+  });
+  return sites;
+}
+
+/**
+ * @param {unknown} context
+ * @returns {string}
+ */
+function sourceText(context) {
+  const ctx =
+    /** @type {{ sourceCode?: { text?: string }, getSourceCode?: () => { text?: string } }} */ (
+      context
+    );
+  return ctx?.sourceCode?.text ?? ctx?.getSourceCode?.()?.text ?? "";
+}
+
 const RAW_TYPOGRAPHY_HATCH = /^Tamagui(?:Text|SizableText|Paragraph|Heading|H[1-6]|Anchor)$/;
 const HOUSE_PACKAGE = /^@multiplatform\.one\//;
 
@@ -105,7 +149,40 @@ export const GEOMETRY_PROPS = Object.freeze([
   "fontSize",
 ]);
 
+/**
+ * Every spelling of an outer margin: the long props @tamagui/helpers registers
+ * and the Tamagui shorthands for them. `00` L9a overrules the LAYOUT_PROPS
+ * allowance for sibling margins above: the place among siblings is the
+ * parent's `gap`.
+ */
+export const MARGIN_PROPS = Object.freeze([
+  "margin",
+  "marginTop",
+  "marginRight",
+  "marginBottom",
+  "marginLeft",
+  "marginHorizontal",
+  "marginVertical",
+  "marginStart",
+  "marginEnd",
+  "marginBlock",
+  "marginBlockStart",
+  "marginBlockEnd",
+  "marginInline",
+  "marginInlineStart",
+  "marginInlineEnd",
+  "m",
+  "mt",
+  "mr",
+  "mb",
+  "ml",
+  "mx",
+  "my",
+]);
+
 const CHROME_PROP_SET = new Set(CHROME_PROPS);
+const MARGIN_PROP_SET = new Set(MARGIN_PROPS);
+const ZERO_MARGIN = /^(?:-?0(?:\.0+)?(?:px)?|\$0)$/;
 const GEOMETRY_PROP_SET = new Set(GEOMETRY_PROPS);
 
 const RULE_OPTIONS_SCHEMA = [
@@ -119,6 +196,48 @@ const RULE_OPTIONS_SCHEMA = [
   },
 ];
 
+const SLOT_MARGIN_OPTIONS_SCHEMA = [
+  {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      slotMargins: { type: "array", items: { type: "string" } },
+    },
+  },
+];
+
+/**
+ * @param {unknown} context
+ * @returns {Set<string>}
+ */
+function resolveSlotMargins(context) {
+  const opt = context?.options?.[0] ?? {};
+  if (Array.isArray(opt.slotMargins)) return new Set(opt.slotMargins);
+  try {
+    return new Set(readSlotMarginRegistry().members);
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * `0` is `00` L8 E1, legal anywhere: a zero-reset is the absence of an outer
+ * margin, not one (Tamagui's own headings ship `margin: 0`).
+ * @param {unknown} value
+ */
+function isZeroMargin(value) {
+  const node = unwrapJsxValue(value);
+  if (!node || typeof node !== "object") return false;
+  const expr =
+    /** @type {{ type?: string, value?: unknown, operator?: string, argument?: unknown }} */ (node);
+  if (expr.type === "Literal") {
+    if (typeof expr.value === "number") return expr.value === 0;
+    if (typeof expr.value === "string") return ZERO_MARGIN.test(expr.value.trim());
+  }
+  if (expr.type === "UnaryExpression" && expr.operator === "-") return isZeroMargin(expr.argument);
+  return false;
+}
+
 /**
  * @param {unknown} context
  * @returns {{ drawings: string[], chromeAllow: Set<string> }}
@@ -330,6 +449,9 @@ export const plugin = {
         if (isPaletteModule(filename)) {
           return {};
         }
+        if (findHexEscapes(sourceText(context)).some((site) => site.reason)) {
+          return {};
+        }
 
         function reportIfColor(node, value) {
           const matched = matchColorLiteral(value);
@@ -445,6 +567,51 @@ export const plugin = {
         return visitors;
       },
     },
+    "no-child-margin": {
+      meta: {
+        type: "problem",
+        docs: {
+          description:
+            "00 L9a: the parent owns the gap. Ban a non-zero margin* prop on any element nested inside another element's JSX, unless the spec declares the element a slot.",
+        },
+        schema: SLOT_MARGIN_OPTIONS_SCHEMA,
+        messages: {
+          childMargin:
+            "{{prop}} on {{name}} is an outer margin on a child (00 L9a). Set `gap` on the parent, express the slot as flex, or declare {{name}} in the spec's ## Slot margins table.",
+        },
+      },
+      create(context) {
+        const slotMargins = resolveSlotMargins(context);
+        let depth = 0;
+        const enter = () => {
+          depth += 1;
+        };
+        const exit = () => {
+          depth -= 1;
+        };
+        return {
+          JSXElement: enter,
+          "JSXElement:exit": exit,
+          JSXFragment: enter,
+          "JSXFragment:exit": exit,
+          JSXOpeningElement(node) {
+            if (depth < 2) return;
+            const name = jsxName(node.name);
+            if (elementAllowKeys(name).some((key) => slotMargins.has(key))) return;
+            for (const attr of node.attributes ?? []) {
+              const prop = jsxAttrName(attr);
+              if (!MARGIN_PROP_SET.has(prop)) continue;
+              if (isZeroMargin(attr.value)) continue;
+              context.report({
+                node: attr,
+                messageId: "childMargin",
+                data: { prop, name: name || "element" },
+              });
+            }
+          },
+        };
+      },
+    },
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/config",
-  "version": "7.10.0",
+  "version": "7.15.0",
   "description": "Shared build and test configuration presets for multiplatform.one",
   "keywords": [
     "config",
@@ -15,14 +15,14 @@
   ],
   "homepage": "https://multiplatform.one",
   "bugs": {
-    "url": "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one/issues",
+    "url": "https://projects.corp.bitspur.com/tracker/MPO",
     "email": "support@risserlabs.com"
   },
   "license": "Apache-2.0",
   "author": "BitSpur <support@risserlabs.com> (https://risserlabs.com)",
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/bitspur/frappe/multiplatform.one.git",
+    "url": "git+https://git.corp.bitspur.com/multiplatform.one/mpo.git",
     "directory": "public/config"
   },
   "source": "src/index.ts",
@@ -34,9 +34,11 @@
     "README.md",
     "oxlint.mjs",
     "oxlint.d.ts",
+    "oxlint.json",
     "lint.mjs",
     "lint.d.ts",
     "drawing-registry.mjs",
+    "spec-registry.mjs",
     "!tsconfig/dist",
     "!tsconfig/types",
     "types",
@@ -84,7 +86,9 @@
     "./tsconfig/app.json": "./tsconfig/app.json",
     "./react-native-config": "./src/react-native.config.cjs",
     "./oxlint": "./oxlint.mjs",
+    "./oxlint.json": "./oxlint.json",
     "./drawing-registry": "./drawing-registry.mjs",
+    "./spec-registry": "./spec-registry.mjs",
     "./lint": {
       "types": "./lint.d.ts",
       "default": "./lint.mjs",
@@ -95,14 +99,14 @@
     "access": "public"
   },
   "dependencies": {
+    "@multiplatform.one/utils": "7.15.0",
     "@tamagui/vite-plugin": "2.7.6",
     "@vitejs/plugin-react": "^6.0.1",
     "dotenv": "^17.4.2",
     "vite": "^8.0.10",
     "vite-plugin-external": "^6.2.2",
     "vite-plugin-i18next-loader": "^3.1.3",
-    "vitest": "^4.1.5",
-    "@multiplatform.one/utils": "7.10.0"
+    "vitest": "^4.1.5"
   },
   "devDependencies": {
     "tsdown": "^0.21.10",

package/spec-registry.mjs

@@ -0,0 +1,183 @@
+/**
+ * Slot-margin, size-recipe-escape and colour-literal-escape registries — parsed from the living
+ * rulebook, the same way drawing-registry.mjs and
+ * scripts/radius-identity-registry.mjs read theirs (MPO-23).
+ *
+ * `00` L8: an escape is declared by name in a committed registry that is
+ * generated from the spec, not from the code, so writing more violations can
+ * never widen the allowlist. Both tables live in
+ * `docs/theme-propagation-spec.md`:
+ *
+ *   ## Slot margins          `| Class | Normative meaning |`, one SLOT-MARGIN
+ *                            row whose **bolded** `Members:` are the element
+ *                            names that may carry a margin (L9a).
+ *   ## Size-recipe escapes   `| File | Reason |`, one row per escape site; the
+ *                            reason is the exact text the code writes (L8 E8).
+ *   ## Colour-literal escapes  `| File | Reason |`, one row per file whose
+ *                            `hex-escape:` comment exempts it from
+ *                            no-hex-literals; same verbatim reason (MPO-326).
+ *
+ * A consumer tree with no spec, or a spec without the section, yields
+ * `present: false` rather than throwing, so shc can pick the rules up before
+ * it has copied the tables.
+ *
+ * Usage:
+ *   import { readSlotMarginRegistry, readSizeRecipeEscapeRegistry, readHexEscapeRegistry } from "./spec-registry.mjs";
+ *   node spec-registry.mjs [--json]
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { defaultSpecPath } from "./drawing-registry.mjs";
+
+export const SLOT_MARGIN_HEADING = "## Slot margins";
+export const SLOT_MARGIN_CLASS = "SLOT-MARGIN";
+export const SIZE_RECIPE_ESCAPE_HEADING = "## Size-recipe escapes";
+export const HEX_ESCAPE_HEADING = "## Colour-literal escapes";
+
+/** `` `a — b` `` → `a — b`. */
+function unwrapCode(cell) {
+  const match = cell.match(/^`(.*)`$/);
+  return match ? match[1] : cell;
+}
+
+/**
+ * Body rows of the first markdown table under `heading`, header and separator
+ * dropped. `null` when the heading is absent.
+ * @param {string} markdown
+ * @param {string} heading e.g. "## Slot margins"
+ * @returns {string[][] | null}
+ */
+export function readSpecTable(markdown, heading) {
+  const lines = markdown.split("\n");
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start === -1) return null;
+  /** @type {string[][]} */
+  const rows = [];
+  let seenTable = false;
+  let seenHeader = false;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (/^#{1,2}\s/.test(line)) break;
+    if (!line.startsWith("|")) {
+      if (seenTable) break;
+      continue;
+    }
+    seenTable = true;
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((cell) => cell.trim());
+    if (/^:?-+:?$/.test(cells[0] ?? "")) continue;
+    if (!seenHeader) {
+      seenHeader = true;
+      continue;
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/** `Members: **Card.Footer**, **Card.Header**.` → ["Card.Footer", "Card.Header"]. */
+function parseMembers(text) {
+  const match = text.match(/Members:\s*(.*)$/i);
+  if (!match) return [];
+  return [...match[1].matchAll(/\*\*([^*]+)\*\*/g)].map((m) => m[1].trim()).filter(Boolean);
+}
+
+/**
+ * @param {string} specPath
+ * @param {string} heading
+ */
+function readTable(specPath, heading) {
+  if (!existsSync(specPath)) return null;
+  return readSpecTable(readFileSync(specPath, "utf8"), heading);
+}
+
+/**
+ * Element names that may carry a margin because the spec declares them an
+ * internal slot (`00` L9a: `Card.Footer` `marginTop: auto` is the precedent).
+ *
+ * @param {string} [specPath]
+ * @returns {{ specPath: string, present: boolean, members: string[] }}
+ */
+export function readSlotMarginRegistry(specPath = defaultSpecPath()) {
+  const rows = readTable(specPath, SLOT_MARGIN_HEADING);
+  if (!rows) return { specPath, present: false, members: [] };
+  const row = rows.find((cells) => cells[0] === SLOT_MARGIN_CLASS);
+  if (!row) {
+    throw new Error(`${specPath}: "${SLOT_MARGIN_HEADING}" has no ${SLOT_MARGIN_CLASS} row`);
+  }
+  return { specPath, present: true, members: parseMembers(row[1] ?? "") };
+}
+
+/**
+ * `| File | Reason |` rows under `heading`: one `{ file, reason }` per row,
+ * placeholder `_(none)_` rows dropped.
+ *
+ * @param {string} specPath
+ * @param {string} heading
+ * @returns {{ specPath: string, present: boolean, escapes: { file: string, reason: string }[] }}
+ */
+function readFileReasonRegistry(specPath, heading) {
+  const rows = readTable(specPath, heading);
+  if (!rows) return { specPath, present: false, escapes: [] };
+  /** @type {{ file: string, reason: string }[]} */
+  const escapes = [];
+  for (const cells of rows) {
+    const file = unwrapCode(cells[0] ?? "");
+    const reason = unwrapCode(cells[1] ?? "");
+    if (!file || /^[_*]?\(none/.test(file)) continue;
+    if (!reason) {
+      throw new Error(`${specPath}: "${heading}" row for ${file} has no reason`);
+    }
+    escapes.push({ file, reason });
+  }
+  return { specPath, present: true, escapes };
+}
+
+/**
+ * Declared size-recipe escape sites: one `{ file, reason }` per row. `file` is
+ * a path from the tree root; `reason` is compared verbatim with the reason the
+ * code writes, so rewording an escape is a spec edit too.
+ *
+ * @param {string} [specPath]
+ * @returns {{ specPath: string, present: boolean, escapes: { file: string, reason: string }[] }}
+ */
+export function readSizeRecipeEscapeRegistry(specPath = defaultSpecPath()) {
+  return readFileReasonRegistry(specPath, SIZE_RECIPE_ESCAPE_HEADING);
+}
+
+/**
+ * Files exempt from `mpo-conventions/no-hex-literals`: one `{ file, reason }`
+ * per row, matched verbatim against the file's `hex-escape:` comment. These
+ * are surfaces no theme token reaches (GTK widget CSS outside the provider, a
+ * content script on third-party pages, the browser badge API, native build
+ * config).
+ *
+ * @param {string} [specPath]
+ * @returns {{ specPath: string, present: boolean, escapes: { file: string, reason: string }[] }}
+ */
+export function readHexEscapeRegistry(specPath = defaultSpecPath()) {
+  return readFileReasonRegistry(specPath, HEX_ESCAPE_HEADING);
+}
+
+const invokedDirectly =
+  typeof process.argv[1] === "string" && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  const slots = readSlotMarginRegistry();
+  const escapes = readSizeRecipeEscapeRegistry();
+  const hexEscapes = readHexEscapeRegistry();
+  if (process.argv.includes("--json")) {
+    console.log(JSON.stringify({ slots, escapes, hexEscapes }, null, 2));
+  } else {
+    console.log(`spec registries from ${slots.specPath}`);
+    console.log(
+      `  SLOT-MARGIN (present=${slots.present}): ${slots.members.join(", ") || "(none)"}`,
+    );
+    console.log(`  size-recipe escapes (present=${escapes.present}):`);
+    for (const { file, reason } of escapes.escapes) console.log(`    ${file} — ${reason}`);
+    console.log(`  colour-literal escapes (present=${hexEscapes.present}):`);
+    for (const { file, reason } of hexEscapes.escapes) console.log(`    ${file} — ${reason}`);
+  }
+}