@assure-one/design-system 1.34.0 → 1.35.0

package/codemods/transforms/cm-06-tone-to-intent.mjs

@@ -0,0 +1,190 @@
+/**
+ * CM-06 — `tone=` → `intent=` on StatusDot, IconTile, Spinner, SegmentedProgress
+ * and SuiteProgress (class R; plan §29 seq 6, registry `C-TONE`).
+ *
+ * W3-21 gave the five components the shared `intent` axis of ADR-007 and kept
+ * `tone` as a deprecated alias. Every legacy word resolves to one intent and
+ * renders the same classes, so the rename is pixel-neutral; the value map is
+ * the components' own alias tables (`STATUS_DOT_TONE_TO_INTENT`, …):
+ *
+ * | component         | `tone` → `intent`                                                          |
+ * | ----------------- | -------------------------------------------------------------------------- |
+ * | StatusDot         | `pro` → `brand`; `danger` `warning` `info` `success` `neutral` unchanged   |
+ * | IconTile          | `pro` → `brand`; status words unchanged; `audit` `books` `tax` → review    |
+ * | Spinner           | `muted` → `neutral`, `accent` → `info`, `destructive` → `danger`, `current` → removed (the default); `success` `warning` unchanged |
+ * | SegmentedProgress | `default` → `brand`, `destructive` → `danger`; `success` `warning` `info` unchanged; `tax` `audit` `accounting` → review |
+ * | SuiteProgress     | `pro` → `brand`; `audit` `books` `tax` → review                            |
+ *
+ * ## What it reports
+ *
+ * | rule            | action  | severity | why                                                                          |
+ * | --------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+ * | `tone-renamed`  | applied | low      | same word on the new axis (or `default` → `brand`, `destructive` → `danger`) |
+ * | `pro-as-brand`  | applied | medium   | `pro` is the brand colour — unless the call site meant "generic purple" (Portal's firm-branded context); a human confirms |
+ * | `tone-removed`  | applied | low      | `tone="current"` on Spinner is the default; the attribute goes                |
+ * | `product-tone`  | review  | medium   | `audit` `books` `tax` `accounting` are product hues, never intents (ADR-007 §2): they stay on `tone` until the products own a service → colour map |
+ * | `dynamic-tone`  | review  | high     | `tone={expr}`: the value is not visible here; map it by hand                  |
+ * | `spread-props`  | review  | medium   | `{...props}` may carry `tone` too; renaming the literal could change which one wins |
+ * | `has-intent`    | review  | low      | both axes present; `intent` already wins, delete `tone` by hand               |
+ * | `unknown-tone`  | review  | high     | a word the component never accepted                                            |
+ *
+ * Elements that already speak `intent` and have no `tone` are not touched
+ * (idempotency). Local components with the same names are not touched; test
+ * files are skipped, as by the scanner that measures C-TONE.
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyEdits, openingOf, removeAttribute, replaceAttribute } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-06",
+  title: "tone → intent on StatusDot, IconTile, Spinner, SegmentedProgress and SuiteProgress",
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-TONE"],
+};
+
+/** Marker: the legacy word has no intent and stays on `tone` (a product hue). */
+export const PRODUCT = Symbol("product-tone");
+/** Marker: the legacy word is the default and the attribute is simply removed. */
+export const REMOVE = Symbol("remove");
+
+/**
+ * `tone` → `intent` per component (mirrors the alias tables in
+ * src/primitives/{status-dot,icon-tile,spinner,segmented-progress,suite-progress}.tsx).
+ */
+export const TONE_MAP = {
+  StatusDot: {
+    danger: "danger",
+    warning: "warning",
+    info: "info",
+    success: "success",
+    pro: "brand",
+    neutral: "neutral",
+  },
+  IconTile: {
+    pro: "brand",
+    neutral: "neutral",
+    info: "info",
+    success: "success",
+    warning: "warning",
+    danger: "danger",
+    audit: PRODUCT,
+    books: PRODUCT,
+    tax: PRODUCT,
+  },
+  Spinner: {
+    current: REMOVE,
+    muted: "neutral",
+    accent: "info",
+    success: "success",
+    warning: "warning",
+    destructive: "danger",
+  },
+  SegmentedProgress: {
+    default: "brand",
+    success: "success",
+    warning: "warning",
+    destructive: "danger",
+    info: "info",
+    tax: PRODUCT,
+    audit: PRODUCT,
+    accounting: PRODUCT,
+  },
+  SuiteProgress: {
+    pro: "brand",
+    audit: PRODUCT,
+    books: PRODUCT,
+    tax: PRODUCT,
+  },
+};
+
+export const TONED_COMPONENTS = new Set(Object.keys(TONE_MAP));
+
+/** The rule a literal tone falls under, or null when the word is unknown. */
+export function classifyTone(component, tone) {
+  const target = TONE_MAP[component]?.[tone];
+  if (target === undefined) return null;
+  if (target === PRODUCT) return { rule: "product-tone", action: "review", severity: "medium" };
+  if (target === REMOVE)
+    return { rule: "tone-removed", action: "applied", severity: "low", intent: null };
+  if (tone === "pro")
+    return { rule: "pro-as-brand", action: "applied", severity: "medium", intent: target };
+  return { rule: "tone-renamed", action: "applied", severity: "low", intent: target };
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const edits = [];
+
+  for (const el of facts.elements) {
+    if (!el.isDs || !TONED_COMPONENTS.has(el.base) || el.component !== el.base) continue;
+    const tone = el.props.get("tone");
+    if (!tone) continue;
+
+    const base = {
+      line: el.line,
+      registryId: "C-TONE",
+      match: `<${el.tag} tone=${tone.text ?? ""}>`,
+      component: el.component,
+      gate: null,
+      detail: {
+        tone: tone.expression ? null : (tone.literals[0] ?? null),
+        dynamic: tone.expression,
+      },
+    };
+    const review = (rule, severity) => findings.push({ ...base, rule, severity, action: "review" });
+
+    if (tone.expression || tone.literals.length !== 1) {
+      review("dynamic-tone", "high");
+      continue;
+    }
+    if (el.spread) {
+      review("spread-props", "medium");
+      continue;
+    }
+    if (el.props.has("intent")) {
+      review("has-intent", "low");
+      continue;
+    }
+    const word = tone.literals[0];
+    const outcome = classifyTone(el.base, word);
+    if (!outcome) {
+      review("unknown-tone", "high");
+      continue;
+    }
+    if (outcome.action === "review") {
+      review(outcome.rule, outcome.severity);
+      continue;
+    }
+    const opening = openingOf(ts, el.node);
+    const edit =
+      outcome.intent === null
+        ? removeAttribute(ts, facts.sf, opening, "tone")
+        : replaceAttribute(ts, facts.sf, opening, "tone", `intent="${outcome.intent}"`);
+    if (!edit) {
+      review("dynamic-tone", "high");
+      continue;
+    }
+    edits.push(edit);
+    findings.push({
+      ...base,
+      rule: outcome.rule,
+      severity: outcome.severity,
+      action: "applied",
+      detail: { ...base.detail, intent: outcome.intent },
+    });
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}

package/codemods/transforms/cm-19-progress-explicit-intent.mjs

@@ -0,0 +1,192 @@
+/**
+ * CM-19 — ProgressBar / ProgressRing: explicit `intent`, the value → colour
+ * rule written down (class R; plan §29 seq 7, registry `C-PROGRESS`).
+ *
+ * The two meters colour themselves **by value** when no colour is passed
+ * (`< 50%` brand, `≥ 50%` warning, `≥ 80%` success) — a business mapping the
+ * design system should not own (Tax lists it as a gotcha), which 2.0 switches
+ * off (W9-10). W3-21 added `intent` to the family; passing it disables the
+ * rule. CM-19 makes every call site say what it renders today, so the flip
+ * changes nothing a consumer did not write down:
+ *
+ * - `variant="<legacy word>"` becomes `intent="<the same colour>"`
+ *   (`default` → `brand`, `destructive` → `danger`, the rest keep their name);
+ * - a meter with no colour and a **literal** `value` (and literal or absent
+ *   `max`) gets the `intent` the rule picks for that value — the auto-colour
+ *   result, preserved and now visible;
+ * - `value={null}` (indeterminate `ProgressBar`) gets `intent="brand"`.
+ *
+ * The rename to the unified `Progress variant="bar" | "ring"` of target
+ * architecture §26 is the second half of this codemod and lands with that
+ * component; today's edit is what makes it a pure rename later.
+ *
+ * ## What it reports
+ *
+ * | rule                        | action  | severity | why                                                                    |
+ * | --------------------------- | ------- | -------- | ---------------------------------------------------------------------- |
+ * | `variant-renamed`           | applied | low      | the colour word moved to the `intent` axis                              |
+ * | `auto-colour-made-explicit` | applied | medium   | the intent the rule picked for a literal value is now written down — a human confirms that colour was the point, not the number |
+ * | `indeterminate-brand`       | applied | low      | an indeterminate track was always brand                                 |
+ * | `dynamic-value`             | review  | high     | no colour and `value={expr}`: the colour depends on runtime data, which is business logic (plan §29 never automates it) |
+ * | `dynamic-variant`           | review  | high     | `variant={expr}`: map the expression's values by hand                   |
+ * | `spread-props`              | review  | medium   | `{...props}` may carry `variant`, `intent` or `value`                    |
+ * | `unknown-variant`           | review  | high     | a word the component never accepted                                     |
+ *
+ * `SegmentedProgress` and `SuiteProgress` have no value → colour rule; their
+ * `tone` moves to `intent` through CM-06. Elements that already pass `intent`
+ * are not touched (idempotency); local components with the same names and
+ * test files are skipped.
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import {
+  applyEdits,
+  attributeNamed,
+  insertAttribute,
+  openingOf,
+  replaceAttribute,
+} from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-19",
+  title: "ProgressBar/ProgressRing: explicit intent, auto-colour written down",
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-PROGRESS"],
+};
+
+/** The meters that colour by value (src/primitives/progress-{bar,ring}.tsx). */
+export const AUTO_COLOURED = new Set(["ProgressBar", "ProgressRing"]);
+
+/** `variant` → `intent` (src/foundation/progress-intent.ts `PROGRESS_LEGACY_TO_INTENT`). */
+export const VARIANT_MAP = {
+  default: "brand",
+  success: "success",
+  warning: "warning",
+  destructive: "danger",
+  info: "info",
+};
+
+/** The default `max` of both meters. */
+export const DEFAULT_MAX = 100;
+
+/** The intent the value rule picks (src/foundation/progress-intent.ts `autoProgressIntent`). */
+export function autoIntent(value, max = DEFAULT_MAX) {
+  const percentage = Math.min(100, Math.max(0, (value / max) * 100));
+  return percentage >= 80 ? "success" : percentage >= 50 ? "warning" : "brand";
+}
+
+/**
+ * The number a JSX attribute passes, when it is a literal: `value={42}`,
+ * `value={-1}`, `value={1.5}`. `null` for `value={null}`, `undefined` for
+ * anything else (an expression, a missing attribute, a string).
+ */
+export function literalNumber(ts, attr) {
+  if (!attr) return undefined;
+  const init = attr.initializer;
+  if (!init || !ts.isJsxExpression(init) || !init.expression) return undefined;
+  let expr = init.expression;
+  while (ts.isParenthesizedExpression(expr)) expr = expr.expression;
+  if (expr.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isNumericLiteral(expr)) return Number(expr.text);
+  if (
+    ts.isPrefixUnaryExpression(expr) &&
+    expr.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(expr.operand)
+  ) {
+    return -Number(expr.operand.text);
+  }
+  return undefined;
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const edits = [];
+
+  for (const el of facts.elements) {
+    if (!el.isDs || !AUTO_COLOURED.has(el.base) || el.component !== el.base) continue;
+    if (el.props.has("intent")) continue;
+
+    const opening = openingOf(ts, el.node);
+    const variant = el.props.get("variant");
+    const base = {
+      line: el.line,
+      registryId: "C-PROGRESS",
+      match: `<${el.tag}>`,
+      component: el.component,
+      gate: null,
+      detail: {
+        variant: variant ? (variant.expression ? null : (variant.literals[0] ?? null)) : undefined,
+        value: undefined,
+        max: undefined,
+        intent: undefined,
+      },
+    };
+    const review = (rule, severity, detail = {}) =>
+      findings.push({
+        ...base,
+        rule,
+        severity,
+        action: "review",
+        detail: { ...base.detail, ...detail },
+      });
+
+    if (el.spread) {
+      review("spread-props", "medium");
+      continue;
+    }
+
+    if (variant) {
+      if (variant.expression || variant.literals.length !== 1) {
+        review("dynamic-variant", "high");
+        continue;
+      }
+      const intent = VARIANT_MAP[variant.literals[0]];
+      if (!intent) {
+        review("unknown-variant", "high");
+        continue;
+      }
+      edits.push(replaceAttribute(ts, facts.sf, opening, "variant", `intent="${intent}"`));
+      findings.push({
+        ...base,
+        rule: "variant-renamed",
+        severity: "low",
+        action: "applied",
+        detail: { ...base.detail, intent },
+      });
+      continue;
+    }
+
+    const value = literalNumber(ts, attributeNamed(ts, opening, "value"));
+    const maxAttr = attributeNamed(ts, opening, "max");
+    const max = maxAttr ? literalNumber(ts, maxAttr) : DEFAULT_MAX;
+    if (value === undefined || max === undefined || max === null) {
+      review("dynamic-value", "high", {
+        value: value === undefined ? null : value,
+        max: max ?? null,
+      });
+      continue;
+    }
+    const intent = value === null ? "brand" : autoIntent(value, max);
+    edits.push(insertAttribute(ts, facts.sf, opening, `intent="${intent}"`, { after: "value" }));
+    findings.push({
+      ...base,
+      rule: value === null ? "indeterminate-brand" : "auto-colour-made-explicit",
+      severity: value === null ? "low" : "medium",
+      action: "applied",
+      detail: { ...base.detail, value, max, intent },
+    });
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}