@assure-one/design-system 1.31.0 → 1.33.0

package/codemods/transforms/cm-20-select-sentinels.mjs

@@ -0,0 +1,442 @@
+/**
+ * CM-20 — Select sentinel finder (class X, report-only; plan §29, registry
+ * `C-SELECT-EMPTY`, feeds Wave 4 W4-08).
+ *
+ * `Select` reserves the empty string for "nothing picked" and Radix refuses
+ * `value=""` on an item, so every application invented a stand-in value for
+ * the "no value" option and converts it back at the form boundary ([CU §18]:
+ * "sentinels, because Select reserves the empty string for 'nothing picked'").
+ * W4-08 gives `Select` a real `value: string | null`.
+ *
+ * Replacing a sentinel with `null` changes what the server receives — the
+ * one thing plan §29 never automates — so CM-20 is report-only for ever. It
+ * finds the sentinels and the line where each is converted; a human decides
+ * what the field should post.
+ *
+ * ## Finding the sentinels rather than assuming them
+ *
+ * `"none"` and `"__unassigned__"` are the two the registry names, but the
+ * applications use many more (`__all__`, `__all_products__`, `__custom__`,
+ * `__scratch__`, `__external__`, `__none__`, …), and `"none"` is also a
+ * perfectly real domain value (`deposit_type: "none"`). A fixed list would
+ * both miss and over-report, so CM-20 works from evidence in the file:
+ *
+ * | evidence     | why it is conclusive                                                     |
+ * | ------------ | ------------------------------------------------------------------------ |
+ * | round trip   | the file converts the value to `null`/`undefined`/`""`, or defaults to it |
+ * | `__dunder__` | the spelling exists only to dodge Radix's empty-value rule                |
+ * | constant name| `NONE_VALUE`, `UNASSIGNED`, `NO_OWNER`, `ALL_MEMBERS`, `…_SENTINEL`       |
+ * | option label | the option is labelled "All …", "None", "Unassigned", "No …"             |
+ *
+ * A spelling is reported only where it is actually used as a `Select` value:
+ * a control's `value`/`defaultValue`, a `SelectItem value`, or the `value`
+ * of an option record in a file that renders one of the Select family. The
+ * same `"__ungrouped__"` used as a grouping key in a table is not a Select
+ * sentinel and stays silent.
+ *
+ * | rule                  | registry        | what it is                                                   |
+ * | --------------------- | --------------- | ------------------------------------------------------------ |
+ * | `empty-string-value`  | C-SELECT-EMPTY  | `value=""` on a Select-family control or an option            |
+ * | `sentinel-dunder`     | C-SELECT-EMPTY  | a `__…__` spelling used as a Select value                     |
+ * | `sentinel-constant`   | C-SELECT-EMPTY  | a no-value-named constant used as a Select value              |
+ * | `sentinel-word`       | C-SELECT-EMPTY  | `none`/`all`/… with a no-value label or a round trip          |
+ * | `sentinel-discovered` | C-SELECT-EMPTY  | any other spelling the file converts to nothing               |
+ * | `sentinel-conversion` | C-SELECT-EMPTY  | the line that maps a reported sentinel to `null`/`undefined`/`""` |
+ *
+ * ## What it deliberately does not do
+ *
+ * - It never writes a file (the runner refuses on class X), and it proposes
+ *   no replacement: whether a field should post `null`, `""` or the sentinel
+ *   is a server contract.
+ * - A known word with no evidence at all (`"none"` as a genuine deposit
+ *   type, `"all"` as a real filter the API understands) is **not** reported.
+ *   CM-20 would rather miss a sentinel than invite someone to change a value
+ *   the backend depends on.
+ * - Sentinels outside the Select family — grouping keys, tab ids, route
+ *   segments — are out of scope even when the spelling matches.
+ * - It does not follow a spelling across files; a sentinel declared in a
+ *   shared constants module and used elsewhere is reported at the use site
+ *   only if that file resolves it.
+ */
+import { analyseForms, literalValue } from "../lib/forms.mjs";
+
+export const meta = {
+  id: "CM-20",
+  title: "Select sentinel finder: option values standing in for “no value”",
+  class: "X",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-SELECT-EMPTY"],
+};
+
+/** How a finding is weighted in the report and in the Wave 4 work. */
+export const SEVERITY = { high: "high", medium: "medium", low: "low" };
+
+/**
+ * The Select family: components whose `value` is an option identifier the
+ * user picks from a list. `DatePicker` and the checkbox-like controls are
+ * not here — they have no "no value" option to spell.
+ */
+export const SELECT_FAMILY = new Set([
+  "Select",
+  "SelectRoot",
+  "SelectItem",
+  "SearchSelect",
+  "ClientSelect",
+  "TeamMemberSelect",
+  "MultiSelectField",
+  "MultiFilterPill",
+  "DisplayMenu",
+  "Combobox",
+]);
+
+/** Attributes of a Select-family element that hold an option value. */
+const VALUE_ATTRIBUTES = ["value", "defaultValue"];
+
+/** Object keys that make an object literal an option record. */
+const LABEL_KEYS = new Set(["label", "labelKey", "title", "name", "text"]);
+
+/** Words that stand in for "no value" often enough to be worth checking. */
+export const NO_VALUE_WORDS = new Set([
+  "none",
+  "all",
+  "any",
+  "unassigned",
+  "unspecified",
+  "unset",
+  "empty",
+  "null",
+  "undefined",
+  "n/a",
+  "na",
+  "-",
+  "--",
+  "—",
+]);
+
+/** A spelling whose only purpose is to dodge Radix's empty-value rule. */
+export const DUNDER = /^__[A-Za-z0-9][\w-]*__$/;
+
+/** A constant name that says the value means "nothing picked". */
+export const SENTINEL_NAME =
+  /(?:^|_)(?:NONE|ALL|ANY|UNASSIGNED|UNSPECIFIED|UNSET|EMPTY|SENTINEL|PLACEHOLDER|NO)(?:_|$)/;
+
+/** A label that says the option is the "no value" one. */
+export const NO_VALUE_LABEL =
+  /(?:^|[.\s_\-—])(?:all|none|any|unassigned|unspecified|unset|empty|everyone|everything|no)(?:[.\s_\-—]|$)/i;
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const sf = facts.sf;
+  const usesSelect = [...facts.componentsUsed].some((c) => SELECT_FAMILY.has(c));
+  if (!usesSelect) return { findings: [], parseErrors: facts.parseErrors };
+
+  const findings = [];
+  const notTransformed = [];
+
+  // -------------------------------------------------------------------------
+  // Evidence 1 — round trips. The file converts a spelling to nothing, or
+  // defaults to it when there is nothing.
+
+  const EMPTY = (node) =>
+    node !== undefined &&
+    node !== null &&
+    ((ts.isStringLiteral(node) && node.text === "") ||
+      node.kind === ts.SyntaxKind.NullKeyword ||
+      (ts.isIdentifier(node) && node.text === "undefined") ||
+      (ts.isNoSubstitutionTemplateLiteral(node) && node.text === ""));
+
+  const stringOf = (node) => {
+    if (!node) return null;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    if (ts.isIdentifier(node)) return facts.constants.get(node.text)?.text ?? null;
+    return null;
+  };
+  /** The declared name behind a value expression, when it is a constant. */
+  const constantName = (node) =>
+    node && ts.isIdentifier(node) && facts.constants.has(node.text) ? node.text : null;
+
+  /** spelling → { line, mapsTo, how } */
+  const roundTrips = new Map();
+  const noteRoundTrip = (spelling, node, mapsTo, how) => {
+    if (spelling === null || spelling === "") return;
+    if (roundTrips.has(spelling)) return;
+    roundTrips.set(spelling, {
+      line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+      mapsTo,
+      how,
+      text: node.getText(sf).replace(/\s+/g, " ").slice(0, 160),
+    });
+  };
+  const emptyName = (node) =>
+    ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)
+      ? '""'
+      : node.kind === ts.SyntaxKind.NullKeyword
+        ? "null"
+        : "undefined";
+
+  /**
+   * The opening elements of the Select family, so that `x ?? SENTINEL` can be
+   * required to sit in a Select's own `value` — `currency ?? "USD"` elsewhere
+   * in the file is a default, not a stand-in for "nothing picked".
+   */
+  const selectOpenings = new Set();
+  for (const el of facts.elements) {
+    if (el.isDs && SELECT_FAMILY.has(el.base)) {
+      selectOpenings.add(ts.isJsxElement(el.node) ? el.node.openingElement : el.node);
+    }
+  }
+  const isSelectValueAttribute = (node) =>
+    ts.isJsxAttribute(node) &&
+    VALUE_ATTRIBUTES.includes(node.name.getText(sf)) &&
+    selectOpenings.has(node.parent?.parent);
+
+  const same = (a, b) => a && b && a.getText(sf).trim() === b.getText(sf).trim();
+
+  const scanEvidence = (node, inSelectValue) => {
+    // The normaliser shape: `x === SENTINEL ? nothing : x`, and its inverse
+    // `x === "" ? SENTINEL : x`. The untouched branch must be the subject
+    // itself — `status === "completed" ? null : "draft"` maps one domain
+    // value onto another and is not a sentinel.
+    if (ts.isConditionalExpression(node)) {
+      const cond = node.condition;
+      if (ts.isBinaryExpression(cond) && /^[=!]==?$/.test(cond.operatorToken.getText(sf))) {
+        const negated = cond.operatorToken.getText(sf).startsWith("!");
+        const [emptyBranch, subjectBranch] = negated
+          ? [node.whenFalse, node.whenTrue]
+          : [node.whenTrue, node.whenFalse];
+        const sides = [cond.left, cond.right];
+        const subject = sides.find((s) => stringOf(s) === null);
+        if (subject && same(subject, subjectBranch) && EMPTY(emptyBranch)) {
+          const spelling = sides.map(stringOf).find((s) => s !== null && s !== "");
+          if (spelling !== undefined) {
+            noteRoundTrip(spelling, node, emptyName(emptyBranch), "conditional");
+          }
+        } else if (subject && same(subject, emptyBranch) && sides.some(EMPTY)) {
+          // `x === "" ? SENTINEL : x` — the sentinel stands in for `""`.
+          const branchSpelling = stringOf(subjectBranch);
+          if (branchSpelling !== null && branchSpelling !== "") {
+            noteRoundTrip(branchSpelling, node, '""', "conditional");
+          }
+        }
+      }
+    }
+    // `x ?? SENTINEL` inside a Select's own `value`: the value the control
+    // shows when the state holds nothing.
+    if (inSelectValue && ts.isBinaryExpression(node)) {
+      const op = node.operatorToken.getText(sf);
+      if (op === "??" || op === "||") {
+        const spelling = stringOf(node.right);
+        if (spelling !== null && spelling !== "" && stringOf(node.left) === null) {
+          noteRoundTrip(spelling, node, "a missing value", "default");
+        }
+      }
+    }
+    const next = inSelectValue || isSelectValueAttribute(node);
+    ts.forEachChild(node, (child) => scanEvidence(child, next));
+  };
+  scanEvidence(sf, false);
+
+  // -------------------------------------------------------------------------
+  // Evidence 2 — option records: `{ value: "…", label: "…" }` anywhere in a
+  // file that renders a Select-family component.
+
+  /** spelling → label text */
+  const optionLabels = new Map();
+  const optionRecords = [];
+  const scanOptions = (node) => {
+    if (ts.isObjectLiteralExpression(node)) {
+      let value = null;
+      let valueNode = null;
+      let label = null;
+      for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop) || !prop.name) continue;
+        const key =
+          ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) ? prop.name.text : null;
+        if (key === "value") {
+          value = stringOf(prop.initializer);
+          valueNode = prop.initializer;
+        } else if (key && LABEL_KEYS.has(key) && label === null) {
+          label = stringOf(prop.initializer);
+        }
+      }
+      if (value !== null && (label !== null || valueNode !== null)) {
+        optionRecords.push({
+          spelling: value,
+          label,
+          node: valueNode,
+          line: sf.getLineAndCharacterOfPosition(valueNode.getStart(sf)).line + 1,
+          constant: constantName(valueNode),
+        });
+        if (label !== null && !optionLabels.has(value)) optionLabels.set(value, label);
+      }
+    }
+    ts.forEachChild(node, scanOptions);
+  };
+  scanOptions(sf);
+
+  // -------------------------------------------------------------------------
+  // Use sites: where a spelling is actually a Select value.
+
+  /** { spelling, line, where, component, label, constant } */
+  const uses = [];
+  for (const el of facts.elements) {
+    if (!el.isDs || !SELECT_FAMILY.has(el.base)) continue;
+    for (const attribute of VALUE_ATTRIBUTES) {
+      const prop = el.props.get(attribute);
+      if (!prop) continue;
+      const direct = literalValue(prop);
+      const spellings = direct !== null ? [direct] : resolveFromExpression(prop);
+      for (const spelling of spellings) {
+        uses.push({
+          spelling,
+          line: prop.line,
+          where: `${attribute} on ${el.component}`,
+          component: el.component,
+          label:
+            el.base === "SelectItem" ? childText(el.node) : (optionLabels.get(spelling) ?? null),
+          constant: prop.identifiers.find((id) => facts.constants.has(id)) ?? null,
+        });
+      }
+    }
+    if (el.spread && !el.props.has("value") && !el.props.has("defaultValue")) {
+      notTransformed.push({
+        line: el.line,
+        reason: "spread-props",
+        detail: `<${el.component} {...props}> — the value is spread in, so the scan cannot read it`,
+      });
+    }
+  }
+  for (const record of optionRecords) {
+    uses.push({
+      spelling: record.spelling,
+      line: record.line,
+      where: "option value",
+      component: null,
+      label: record.label,
+      constant: record.constant,
+    });
+  }
+
+  /**
+   * The spellings a `value={…}` expression can hold. The empty string is
+   * excluded on purpose: inside an expression it is the *result* of a
+   * conversion (`x === SENTINEL ? "" : x`), not a `value=""` the control is
+   * given, and `empty-string-value` is about the latter.
+   */
+  function resolveFromExpression(prop) {
+    const out = [];
+    for (const id of prop.identifiers) {
+      const constant = facts.constants.get(id);
+      if (constant) out.push(constant.text);
+    }
+    for (const literal of prop.literals) out.push(literal);
+    return [...new Set(out)].filter((s) => s !== "");
+  }
+
+  /** The text children of a `<SelectItem>`, its visible label. */
+  function childText(node) {
+    if (!node || !ts.isJsxElement(node)) return null;
+    const parts = node.children
+      .filter((c) => ts.isJsxText(c))
+      .map((c) => c.text.trim())
+      .filter(Boolean);
+    return parts.length ? parts.join(" ").slice(0, 80) : null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Classification.
+
+  const reported = new Set();
+  const reportedSpellings = new Set();
+  for (const use of uses) {
+    const key = `${use.line}:${use.spelling}:${use.where}`;
+    if (reported.has(key)) continue;
+    reported.add(key);
+    const trip = roundTrips.get(use.spelling) ?? null;
+    const labelled = use.label !== null && NO_VALUE_LABEL.test(use.label);
+    const named = use.constant !== null && SENTINEL_NAME.test(use.constant);
+
+    let rule = null;
+    let severity = SEVERITY.medium;
+    let confidence = "high";
+    if (use.spelling === "") {
+      rule = "empty-string-value";
+      severity = SEVERITY.high;
+    } else if (DUNDER.test(use.spelling)) {
+      rule = "sentinel-dunder";
+      severity = trip ? SEVERITY.high : SEVERITY.medium;
+    } else if (named) {
+      rule = "sentinel-constant";
+      severity = trip ? SEVERITY.high : SEVERITY.medium;
+      confidence = trip || labelled ? "high" : "medium";
+    } else if (NO_VALUE_WORDS.has(use.spelling.toLowerCase())) {
+      // A known word is only a sentinel with evidence: `"none"` is also a
+      // real deposit type and `"all"` a real filter the API understands.
+      if (!trip && !labelled) continue;
+      rule = "sentinel-word";
+      severity = trip ? SEVERITY.high : SEVERITY.medium;
+      confidence = trip ? "high" : "medium";
+    } else if (trip) {
+      // A spelling no list would have predicted. A conditional that maps it
+      // to nothing is conclusive; a `??` default inside the Select's own
+      // value is weaker — it may be a deliberate default role or currency
+      // rather than a stand-in for "nothing picked".
+      rule = "sentinel-discovered";
+      severity = trip.how === "conditional" ? SEVERITY.high : SEVERITY.medium;
+      confidence = trip.how === "conditional" ? "high" : "medium";
+    } else continue;
+
+    reportedSpellings.add(use.spelling);
+    findings.push({
+      line: use.line,
+      registryId: "C-SELECT-EMPTY",
+      gate: null,
+      severity,
+      rule,
+      scope: use.where,
+      component: use.component,
+      match: JSON.stringify(use.spelling),
+      detail: {
+        spelling: use.spelling,
+        constant: use.constant,
+        label: use.label,
+        mapsTo: trip?.mapsTo ?? null,
+        conversionLine: trip?.line ?? null,
+      },
+      confidence,
+    });
+  }
+
+  // The conversion site itself: the line where the server contract is
+  // decided, reported once per reported spelling.
+  for (const [spelling, trip] of [...roundTrips].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (!reportedSpellings.has(spelling)) continue;
+    findings.push({
+      line: trip.line,
+      registryId: "C-SELECT-EMPTY",
+      gate: null,
+      severity: SEVERITY.medium,
+      rule: "sentinel-conversion",
+      scope: trip.how,
+      component: null,
+      match: trip.text,
+      detail: { spelling, mapsTo: trip.mapsTo, constant: null, label: null, conversionLine: null },
+      confidence: trip.how === "conditional" ? "high" : "medium",
+    });
+  }
+
+  return {
+    findings,
+    notTransformed,
+    parseErrors: facts.parseErrors,
+    context: {
+      sentinels: [...reportedSpellings].sort(),
+      roundTrips: [...roundTrips.keys()].sort(),
+    },
+  };
+}

package/dist/css/base.css

@@ -0,0 +1,60 @@
+/* Optional document defaults (W1-15).
+ *
+ * Hand-written, not generated: it carries no token values, only references.
+ *
+ * `styles.css` ships a Tailwind preflight, `h1`–`h4` element styles, a global
+ * number-spinner rule, a global `::selection` rule and a body font size into
+ * every host. Target architecture §13 gives all of that back to the
+ * application, and this file is the small, opt-in replacement for the part an
+ * application usually does want: the document's background, ink, font and
+ * colour scheme, expressed as references to `--ds-*` tokens.
+ *
+ * What this file deliberately does NOT contain:
+ *   - no preflight and no reset. DS components are written to be correct given
+ *     a modern reset, which every known consumer already has (an app that has
+ *     none needs its own; §13).
+ *   - no element rules beyond `html` and `body`. No `h1`–`h4` (that is what
+ *     `Heading` is for), no `input[type=number]` spinner rule (scoped to
+ *     `NumberInput` instead), no global `*` box-sizing, no global
+ *     reduced-motion override (durations collapse at the token level).
+ *   - no `@import url(…)`: the design system loads no fonts. The application
+ *     owns font loading and sets `--ds-font-sans` (§14, D2). Until it does,
+ *     `--ds-font-sans` resolves to whatever `css/tokens.css` declares.
+ *   - no `font-size`. `styles.css` sets the body to 14px; this file does not
+ *     restore that, because a document base size is the application's
+ *     decision. Moving an app to the new CSS mode is a deliberate visual
+ *     change for exactly this kind of reason (ADR-004 rule 10, plan §12.4).
+ *
+ * Importing the file is the opt-in. Everything in it sits in `@layer base`, so
+ * an application's own base rules — declared later in the same layer — win,
+ * and any utility in a higher layer wins over all of it.
+ */
+
+@layer theme, base, ds, components, utilities;
+
+@layer base {
+  /* Tells the browser which form controls, scrollbars and default canvas to
+   * render. Both spellings of the scope, as everywhere in the new mode. */
+  html {
+    color-scheme: light;
+  }
+
+  html:where([data-ds-scheme="dark"], .dark) {
+    color-scheme: dark;
+  }
+
+  body {
+    background-color: var(--ds-color-canvas);
+    color: var(--ds-color-content);
+    font-family: var(--ds-font-sans);
+  }
+
+  /* Selection ink. Scoped to the document body rather than written as a bare
+   * `::selection`, so the rule cannot reach a shadow host or a detached
+   * subtree the application renders outside `<body>`. */
+  body::selection,
+  body *::selection {
+    background-color: var(--ds-color-action-brand-subtle-bg);
+    color: var(--ds-color-content);
+  }
+}