@assure-one/design-system 1.34.0 → 1.36.0

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,
+  };
+}