@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/lint/design/tokens.mjs

@@ -0,0 +1,128 @@
+/**
+ * THE TOKEN REGISTRY — does the name a definition writes actually resolve?
+ *
+ * LAW 1 (file.mjs) bans a RAW value: `#ff0000`, `12px`. It says nothing about a name that
+ * looks like a token and is not one, and that is the half that fails silently. The SDK's
+ * interpreter resolves every style value as `theme.<bucket>[name] ?? name` (sdk/style.ts),
+ * so an unknown name is not an error anywhere in the stack — it is handed to CSS verbatim,
+ * CSS discards the declaration, and the element renders with that property simply absent.
+ * `radius: lgg` is a square corner with a green lint run behind it. `font: headline.enormous`
+ * is worse still: `font` is applied only when the lookup HITS, so an invented text style
+ * applies nothing at all and the text falls back to whatever it inherits.
+ *
+ * One namespace was already covered — the space scale, via `checkDimension` — and that is
+ * the shape this generalises: every other bucket the interpreter reads gets the same
+ * treatment, from the same files the server resolves at serve time.
+ *
+ * THE REGISTRY IS BUILT THE WAY THE SERVER BUILDS IT (definitions/theme.ts `buildTheme`):
+ * the marketplace foundation's `base` + `semantic` first, then the org's ON TOP, per token
+ * — an org omits a token to inherit it. Themes are UNIONED rather than resolved one at a
+ * time, because a name that resolves under `dark` is legitimate work; per-theme parity is
+ * a different rule with its own guard (apps/unoverse/server/tests/design/theme-contract.test.ts).
+ *
+ * UNREADABLE IS NOT EMPTY. A developer's project has no design system on disk — it is
+ * installed, not authored — so the foundation half cannot be read and only the org's own
+ * names are left. Judging real work against half the answer rejects it, and publishing
+ * lints first, so that reads as "you cannot publish". `null` = abstain, exactly as
+ * `appSizesForFile` abstains, and for the same reason.
+ */
+import { readdirSync, existsSync } from "node:fs";
+import { join, sep } from "node:path";
+import { isDefFile, readDef } from "./defs.mjs";
+
+/** Flatten a token file into { "dotted.path": rawValue } — mirrors theme.ts `collect`. */
+function collect(obj, prefix, out) {
+  if (!obj || typeof obj !== "object") return;
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith("$")) continue;
+    if (v && typeof v === "object" && "$value" in v) out[prefix ? `${prefix}.${k}` : k] = v.$value;
+    else if (v && typeof v === "object") collect(v, prefix ? `${prefix}.${k}` : k, out);
+  }
+}
+
+/** Read every token file in a dir into the flat registry. A malformed file lints on its own. */
+function readTokenDir(dir, into) {
+  if (!existsSync(dir)) return;
+  for (const f of readdirSync(dir).filter(isDefFile)) {
+    try {
+      collect(readDef(join(dir, f)), "", into);
+    } catch {
+      /* the file has its own findings */
+    }
+  }
+}
+
+/** Every theme in a folder, merged into one registry — see the union note in buildTokens. */
+function readThemes(dir, into) {
+  if (!existsSync(dir)) return;
+  for (const f of readdirSync(dir).filter(isDefFile)) {
+    try {
+      collect(readDef(join(dir, f)), "", into);
+    } catch {
+      /* the file has its own findings */
+    }
+  }
+}
+
+/** The leaf names under a dotted prefix: `color.` → { "text.primary", "border.strong", … }. */
+const names = (reg, prefix) =>
+  new Set(Object.keys(reg).filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length)));
+
+/**
+ * Build the name sets one home (the design system, or an org) resolves against.
+ * Returns null when the foundation cannot be read — see the header.
+ */
+function buildTokens(dsStyles, homeStyles) {
+  const reg = {};
+  const foundation = existsSync(join(dsStyles, "base")) || existsSync(join(dsStyles, "semantic"));
+  const ownFoundation = homeStyles === dsStyles;
+  if (!foundation && !ownFoundation) return null; // abstain: half an answer judges nothing
+  if (!ownFoundation) {
+    readTokenDir(join(dsStyles, "base"), reg);
+    readTokenDir(join(dsStyles, "semantic"), reg);
+  }
+  readTokenDir(join(homeStyles, "base"), reg);
+  readTokenDir(join(homeStyles, "semantic"), reg);
+  /**
+   * Colours live in the THEMES, and a home has several. Union them, foundation first:
+   *
+   *  - across a home's own themes, because a name only `dark` defines is real work, not a
+   *    typo (whether every theme defines every name is a DIFFERENT rule, guarded by
+   *    apps/unoverse/server/tests/design/theme-contract.test.ts — this one must not double as a weaker copy);
+   *  - the foundation's underneath, because the colour contract is the shared one every
+   *    org is written against. An org that has no themes folder of its own would otherwise
+   *    read as "no colours exist", and the rule would report every colour it uses.
+   */
+  if (!ownFoundation) readThemes(join(dsStyles, "themes"), reg);
+  readThemes(join(homeStyles, "themes"), reg);
+  // A styles set with no colour at all is not a set — treat it as unreadable rather than
+  // reporting every colour in the org as invented.
+  const color = names(reg, "color.");
+  if (color.size === 0) return null;
+  return {
+    color,
+    radius: names(reg, "radius."),
+    shadow: names(reg, "shadow."),
+    borderWidth: names(reg, "border.width."),
+    weight: names(reg, "font.weight."),
+    lineHeight: names(reg, "font.lineHeight."),
+    text: names(reg, "text."),
+    icons: names(reg, "icons."),
+    keyframes: names(reg, "keyframes."),
+  };
+}
+
+/**
+ * `tokensForFile(file)` → the name sets that file's home resolves against, or null to
+ * abstain. Cached per home; the cache lives for the run, like `appSizesCache`.
+ */
+export function makeTokensForFile({ DS, orgDirs }) {
+  const cache = new Map();
+  const dsStyles = join(DS, "styles");
+  return function tokensForFile(file) {
+    const home = orgDirs.find((d) => file.startsWith(d + sep)) ?? (file.startsWith(DS + sep) ? DS : null);
+    if (!home) return null;
+    if (!cache.has(home)) cache.set(home, buildTokens(dsStyles, join(home, "styles")));
+    return cache.get(home);
+  };
+}

package/vendor/base/src/lint/design/vocabulary.mjs

@@ -0,0 +1,181 @@
+/**
+ * The CLOSED SETS. This file is the linter's ground truth.
+ *
+ * Mirrors apps/unoverse/design/_schema/unoverse.schema.json and the server guards, and UNOVERSE_CONFORMANCE
+ * §5 makes keeping them equal a maintenance rule: "One source for each closed set... Keep
+ * them equal or they disagree silently."
+ *
+ * They are closed on purpose. An invented primitive has no renderer; an invented style key
+ * is silently dropped cross-platform. Compose from what exists, do not extend these
+ * without extending the schema and the SDK in the same change.
+ */
+
+// ── ground truth (mirrors design/_schema/unoverse.schema.json + server guards) ──
+export const PRIMITIVES = new Set([
+  "Box", "Stack", "Row", "Column", "Each", "Switch", "ComponentSlot", "Timeline",
+  "Text", "Image", "Button", "Input", "Select", "Markdown", "Skeleton", "Icon", "Ref", "Orb", "Template",
+]);
+export const CONDITION_KEYS = new Set(["field", "eq", "ne", "in"]);
+
+/**
+ * WHAT EACH PRIMITIVE IS (UNOVERSE_CONFORMANCE §2a, UNOVERSE_PRIMITIVE_CONTRACT.md).
+ *
+ * Until 2026-08-23 nothing stated this. Every node shared one bag of 36 optional properties,
+ * so `{ type: "Image", bind: { value: photo } }` saved, linted, published and drew nothing —
+ * the silent class behind "the card streams its title but keeps its mock image".
+ *
+ * Merged from three sources: `core/types.ts` JSDoc (25 of 32 properties already named their
+ * owner in prose, where no tool could read it), the renderer (the only authority on which
+ * `bind` keys are consumed), and what shipped definitions actually use — types.ts was
+ * missing nine properties in live use, because YAML never meets a TypeScript interface.
+ *
+ * `packages/sdk/conformance/tools/build-primitive-schema.mjs` reads THIS to emit the JSON
+ * Schema halves, so the editor squiggle and the publish gate cannot disagree.
+ */
+export const UNIVERSAL_PROPS = new Set([
+  // read for every node before dispatch. `brief` is GONE (UNOVERSE_AUTHORING §3b, ruled
+  // 2026-08-30): a field's contract lives on its prop, and the layout only arranges.
+  "type", "style", "visibleWhen", "bind", "action", "analytics", "skeleton", "$include",
+]);
+
+/**
+ * A PROP, whole (UNOVERSE_AUTHORING §3b): JSON Schema's own words plus the platform's
+ * four. Closed, because the prop is now the only place a field's contract can live —
+ * a misspelled `maxlength` there is a limit that silently never applies.
+ */
+export const PROP_KEYS = [
+  "type", "input", "description", "maxLength", "minItems", "maxItems",
+  "hydrate", "override", "optional", "enum", "preview", "default", "items",
+];
+
+/**
+ * THE INTERFACE FIELDS (packages/docs/design/interface-data.md): the names a content row
+ * carries. A row fills a component BY NAME with no mapping layer, so a prop wearing one
+ * of these names is filled by the delivery — whatever the definition declares about it.
+ * Layer 1 arrives with every card; the `service`/`need` editorial fields arrive with the
+ * row that has them; layer 2 arrives when `getDetail` runs.
+ */
+export const INTERFACE_FIELDS = new Set([
+  "universal_id", "title", "description", "object_type", "key_need", "source_url", "source_id",
+  "tagline", "shortDescription", "introParagraph", "callToAction", "actionPrompt", "primaryImage", "images", "action",
+  "bodyCopy", "features", "mainCategory", "section", "needs",
+]);
+
+/**
+ * The keys that only make sense if an AUTHOR, not a delivery, decides the value — a cap,
+ * a count, a closed set. `description` is deliberately NOT one: every prop describes
+ * itself as standard (UNOVERSE_AUTHORING §3b), including the ones a row fills, so
+ * flagging a described `title` would fire on every content card in the estate and teach
+ * people to ignore the rule. What is worth saying is narrower and still true: a LIMIT you
+ * wrote does not apply to a value the delivery brings.
+ */
+export const AUTHORED_CONTROLS = ["maxLength", "minItems", "maxItems", "enum"];
+
+export const PRIMITIVE_PROPS = {
+  Box: ["children", "autoScroll", "revealOnStick", "selection", "appWidth"],
+  Stack: ["children", "autoScroll", "revealOnStick", "appWidth"],
+  Row: ["children", "autoScroll", "revealOnStick", "appWidth"],
+  Column: ["children", "autoScroll", "revealOnStick", "appWidth"],
+  Text: ["value"],
+  Image: ["src", "alt"],
+  Markdown: ["value", "inheritLinkColor"],
+  Icon: ["icon", "name"],
+  Skeleton: ["variant"],
+  Orb: ["state", "size"],
+  Button: ["children", "value", "label", "icon", "disabledWhen"],
+  Input: ["placeholder", "inputType", "disabledWhen", "maxLength", "multiline", "rows",
+          "inputMode", "autoComplete", "advanceOnFill"],
+  Select: ["placeholder", "options", "disabledWhen"],
+  Each: ["item", "app", "items"],
+  Switch: ["on", "cases", "fallback"],
+  Ref: ["ref", "props", "with", "children", "name"],
+  ComponentSlot: ["select", "frame", "fallback", "pinned", "appWidth"],
+  // THE MOUNT (UNOVERSE_TEMPLATE_MODEL §12): a layout place that runs a mounted
+  // template's machinery. `name` addresses the manifest's `templates:` entry;
+  // `frame` is the dressing drawn around it when occupied.
+  Template: ["name", "frame", "template", "director", "appWidth"],
+  Timeline: ["user", "assistant", "userData", "assistantData", "autoScroll"],
+};
+
+/** Which `bind` keys each primitive's view actually reads. Absent = the view reads the whole
+ *  bind object (Orb), so any key is legitimate. */
+export const PRIMITIVE_BINDS = {
+  Text: ["value"], Image: ["src", "alt"], Markdown: ["value"], Icon: ["name"],
+  Button: ["label"], Input: ["value", "placeholder"], Select: ["options", "value"],
+  Each: ["items"],
+};
+// the portable style vocabulary — every key the SDK interpreter maps (sdk/style.ts).
+// Each is a neutral intent every native renderer (iOS/Android/RN/Flutter) implements;
+// an unknown key is a typo or a web-ism that renders nowhere.
+export const STYLE_KEYS = new Set([
+  "width", "height", "maxWidth", "minWidth", "minHeight", "maxHeight", "flex",
+  "padding", "margin", "gap", "overflow",
+  "position", "inset", "top", "right", "bottom", "left", "zIndex",
+  "direction", "wrap", "align", "justify", "display", "columns", "span", "stackBelow", "container", "hideBelow", "hideAbove",
+  "background", "radial", "border", "borderTop", "borderRight", "borderBottom", "borderLeft",
+  "outline", "shadow", "radius", "radiusTopLeft", "radiusTopRight", "radiusBottomLeft", "radiusBottomRight",
+  "font", "weight", "lineHeight", "color", "textAlign", "fit",
+  "transform", "transition", "animation", "animationDelay", "cursor",
+  "hover", "active", "when",
+]);
+// exact regex from server/src/runtime/definition-tokens.test.ts
+export const RAW_VALUE = /#[0-9a-fA-F]{3,8}\b|\b\d*\.?\d+(px|rem|em)\b/;
+// nodes reachable through these keys (data keys like `items`/`cases` handled explicitly)
+export const CHILD_NODE_KEYS = ["children", "item", "fallback", "user", "assistant"];
+// folders that hold BARE PARTIALS one level under the definition root
+export const PARTIAL_DIRS = new Set(["layouts", "states", "components", "blocks"]);
+
+/** Style keys whose value is a dimension, so it must be a space-scale step. */
+export const DIMENSION_KEYS = new Set([
+  "width", "height", "maxWidth", "minWidth", "minHeight", "maxHeight",
+  "gap", "padding", "margin", "top", "right", "bottom", "left", "inset",
+  // width THRESHOLDS, named on the same scale as any other width
+  "hideBelow", "hideAbove", "stackBelow",
+]);
+
+/**
+ * WHICH THEME BUCKET EACH STYLE KEY RESOLVES AGAINST — mirrors sdk/style.ts `computeCss`,
+ * which is the only place that decides it. Dimensions are absent because the space scale
+ * has its own check (`checkDimension`); `border*` is absent because its value is a PAIR
+ * (an optional width token + a colour token) and is destructured separately.
+ *
+ * A key the interpreter passes straight through (`overflow`, `outline`, `cursor`,
+ * `transform`, `transition`, `position`, `display`, …) is absent on purpose: there is no
+ * bucket to check it against, so there is nothing here to be wrong about.
+ */
+export const TOKEN_KEYS = {
+  background: "color",
+  color: "color",
+  shadow: "shadow",
+  radius: "radius",
+  radiusTopLeft: "radius",
+  radiusTopRight: "radius",
+  radiusBottomLeft: "radius",
+  radiusBottomRight: "radius",
+  font: "text",
+  lineHeight: "lineHeight",
+};
+
+/**
+ * CSS keywords a token key may legitimately carry instead of a token name. Kept tiny on
+ * purpose: every one of these is a value with no token equivalent, and anything else that
+ * "just works in CSS" is precisely the web-ism the closed vocabulary exists to keep out.
+ */
+export const LITERAL_VALUES = new Set(["none", "transparent", "inherit", "currentColor", "unset", "initial", "auto"]);
+
+/**
+ * CSS sizing keywords a dimension may carry that are NOT scale steps. `full` and `auto`
+ * are already seeded into the scale itself (the SDK special-cases `full` → 100%); these
+ * are the intrinsic-sizing words a layout legitimately needs and no token can express.
+ */
+export const DIMENSION_LITERALS = new Set([
+  "auto", "full", "none", "inherit", "unset", "initial",
+  "fit-content", "min-content", "max-content",
+]);
+
+/**
+ * `weight` used to be the exception here: the SDK held the scale as a literal four-name
+ * map, so this file had to mirror THAT rather than the tokens. It now resolves from
+ * `theme.weight` like every other value, so it is an ordinary entry above and this note
+ * only survives to say why one is not needed.
+ */