sellmate-design-system-react 4.1.0 → 4.3.0

package/eslint/rules/no-off-scale-spacing.mjs

@@ -9,6 +9,11 @@
  * 소비 앱이 원래 쓰던 Tailwind 코드이기 때문이다. 간격을 디자인 시스템 스케일로
  * 통일하는 팀만 `requirePrefix: true` 로 켠다.
  *
+ * 접두가 없는 클래스는 **깨진 코드가 아니라 다른 값으로 정상 동작하는 코드**다
+ * (`p-16` = 64px). 그래서 `sd-` 로 옮기는 것은 표기 정규화가 아니라 값 변경이고,
+ * 자동 수정(fix)이 아니라 제안(suggestion)으로만 낸다. 일괄 마이그레이션이
+ * 필요한 팀은 `unsafeFix: true` 로 명시적으로 켠다.
+ *
  * AGENTS.md §2-2.
  */
 import { collectClassTokens, stripVariants, stripModifiers } from "../lib/class-names.mjs";
@@ -23,28 +28,47 @@ const SPACING_PREFIXES = [
 ];
 
 const ALLOWED = new Set([0, ...SPACING]);
+const MAX = Math.max(...SPACING);
+
+/** Tailwind 기본 스케일에서 `p-<n>` 이 실제로 만드는 px (`--spacing` = 0.25rem) */
+const RENDERED_PX = (value) => value * 4;
 
 const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
+/**
+ * 토큰 시작 경계 — 앞은 공백이거나 문자열 따옴표(= 문자열의 시작)여야 한다.
+ * `(?<![\w-])` 만 쓰면 `md:p-4 p-4` 에서 `p-4` 를 찾을 때 variant 안쪽(`md:` 뒤)이
+ * 먼저 걸려 엉뚱한 클래스를 고친다.
+ */
+const TOKEN_START = "(?<![^\\s'\"`])";
+
 export default {
   meta: {
     type: "problem",
     docs: {
       description: "간격 유틸리티는 sd- 접두가 붙은 토큰 스케일 값만 사용",
     },
+    // 스케일 밖 값(`gap-sd-13`)에는 fix 를 내지 않는다. `unsafeFix` 를 켠 팀의
+    // 접두 누락 수정에만 쓰이지만, 선언은 정적이어야 하므로 여기 남는다.
     fixable: "code",
+    hasSuggestions: true,
     schema: [
       {
         type: "object",
         properties: {
           /**
            * 접두 없는 간격 유틸리티(`p-16`)도 잡는다. 기본 false.
-           *
-           * ⚠️ 자동 수정은 "클래스의 숫자 = px" 를 전제로 `p-16` → `p-sd-16` 로 바꾼다.
-           * 기본 Tailwind 스케일(`p-4` = 16px)로 쓰던 앱에서 켜면 여백이 1/4 로 줄어드니,
-           * 이전 버전의 디자인 시스템 스케일을 쓰던 앱에서만 켠다.
+           * 기본값에서는 두 해석(`p-sd-16` = 16px / 현재 값 유지)을 제안으로만 낸다.
            */
           requirePrefix: { type: "boolean" },
+          /**
+           * 접두 누락을 "클래스의 숫자 = px" 로 단정하고 `p-16` → `p-sd-16` 자동 수정한다.
+           *
+           * ⚠️ **여백 값이 바뀐다.** 기본 Tailwind 스케일(`p-4` = 16px)로 쓰던 앱에서
+           * 켜면 여백이 1/4 로 줄어든다. 이전 버전의 디자인 시스템 스케일을 쓰던 앱을
+           * 한 번에 옮길 때만 켜고, 마이그레이션이 끝나면 다시 끈다.
+           */
+          unsafeFix: { type: "boolean" },
         },
         additionalProperties: false,
       },
@@ -52,32 +76,57 @@ export default {
     messages: {
       offScale:
         "`{{token}}` 의 {{value}} 는 간격 스케일에 없어 스타일이 적용되지 않습니다. 가까운 값: {{nearest}}. (AGENTS.md §2-2)",
-      missingPrefix:
-        "`{{token}}` 은 Tailwind 기본 스케일이라 {{actual}}px 이 적용됩니다. 디자인 시스템 간격 {{value}}px 을 쓰려면 `{{suggestion}}` 로 적으세요. (AGENTS.md §2-2)",
-      missingPrefixOffScale:
-        "`{{token}}` 은 Tailwind 기본 스케일이라 {{actual}}px 이 적용됩니다. {{value}} 는 간격 스케일에도 없으니 가까운 값으로 `{{prefix}}-sd-{{nearest}}` 를 쓰세요. (AGENTS.md §2-2)",
+      // 접두 누락 — 어느 해석이 스케일에 있느냐로 갈린다.
+      // `p-16` 은 지금 64px 이므로 "16px 의도" 와 "64px 유지" 가 서로 다른 결과다.
+      missingPrefixBoth:
+        "`{{token}}` 은 현재 {{actual}}px 입니다 (Tailwind 기본 스케일). {{value}}px 을 의도했다면 → `{{asLiteral}}` · {{actual}}px 을 유지하려면 → `{{asRendered}}` (AGENTS.md §2-2)",
+      missingPrefixLiteral:
+        "`{{token}}` 은 현재 {{actual}}px 입니다 (Tailwind 기본 스케일). {{value}}px 을 의도했다면 → `{{asLiteral}}`. {{actual}}px 유지는 간격 스케일에 값이 없습니다. {{fallback}} (AGENTS.md §2-2)",
+      missingPrefixRendered:
+        "`{{token}}` 은 현재 {{actual}}px 입니다 (Tailwind 기본 스케일). {{actual}}px 을 유지하려면 → `{{asRendered}}`. {{value}}px 은 간격 스케일에 없습니다. (AGENTS.md §2-2)",
+      missingPrefixNone:
+        "`{{token}}` 은 현재 {{actual}}px 입니다 (Tailwind 기본 스케일). {{value}}px·{{actual}}px 둘 다 간격 스케일에 없습니다. {{fallback}} (AGENTS.md §2-2)",
+      // 제안(suggestion) 설명 — 편집기 목록에 그대로 뜬다
+      useLiteral: "`{{to}}` 적용 — 숫자를 px 로 해석 ({{actual}}px → {{value}}px, 여백이 바뀝니다)",
+      useRendered: "`{{to}}` 적용 — 현재 {{actual}}px 유지",
     },
   },
 
   create(context) {
     const sourceCode = context.sourceCode ?? context.getSourceCode();
     const requirePrefix = context.options[0]?.requirePrefix ?? false;
+    const unsafeFix = context.options[0]?.unsafeFix ?? false;
 
     /** 토큰 문자열을 소스에서 찾아 치환하는 fixer (없으면 null) */
     const replaceToken = (valueNode, token, fixed) => (fixer) => {
       const text = sourceCode.getText(valueNode);
-      const idx = text.search(new RegExp(`(?<![\\w-])${escapeRegExp(token)}(?![\\w-])`));
+      const idx = text.search(new RegExp(`${TOKEN_START}${escapeRegExp(token)}(?![\\w-])`));
       if (idx === -1) return null;
       const start = valueNode.range[0] + idx;
       return fixer.replaceTextRange([start, start + token.length], fixed);
     };
 
-    /** 스케일에서 value 에 가장 가까운 값 두 개 */
-    const nearestOf = (value) =>
-      [...ALLOWED]
-        .sort((a, b) => Math.abs(a - value) - Math.abs(b - value))
-        .slice(0, 2)
-        .sort((a, b) => a - b);
+    /** 스케일을 value 와의 거리순으로 (동률이면 작은 값 먼저) */
+    const byDistance = (value) =>
+      [...ALLOWED].sort((a, b) => Math.abs(a - value) - Math.abs(b - value) || a - b);
+
+    /** 가장 가까운 값 하나 — 거리순 배열을 다시 정렬하면 안 된다 (64 → 62 지 60 이 아니다) */
+    const nearestOne = (value) => byDistance(value)[0];
+
+    /** 스케일에서 value 에 가장 가까운 값 두 개 (표시용이라 오름차순) */
+    const nearestOf = (value) => byDistance(value).slice(0, 2).sort((a, b) => a - b);
+
+    /**
+     * 대응 토큰이 없을 때의 안내. 기준은 클래스에 적힌 숫자가 아니라 **실제 렌더 px** 다.
+     * 스케일 최대를 넘으면 가까운 값을 권하는 것 자체가 무의미하므로 토큰 추가로 안내한다.
+     */
+    const fallbackFor = (prefix, renderedPx) => {
+      if (renderedPx > MAX) {
+        return `간격 스케일 최대가 ${MAX}px 이라 대응 토큰이 없습니다 — 토큰 추가를 요청하세요.`;
+      }
+      const near = nearestOne(renderedPx);
+      return `가까운 \`${prefix}-sd-${near}\`(${near}px) 를 검토하거나 토큰 추가를 요청하세요.`;
+    };
 
     return {
       JSXAttribute(node) {
@@ -99,31 +148,61 @@ export default {
             const value = Number(raw);
             if (value === 0) continue; // p-0 은 스케일과 무관하게 0
 
-            // 스케일에 없는 값은 sd- 를 붙여도 동작하지 않으므로 자동 수정하지 않는다
-            if (!ALLOWED.has(value)) {
-              context.report({
-                node: valueNode,
-                messageId: "missingPrefixOffScale",
-                data: {
-                  token,
-                  value: raw,
-                  actual: String(value * 4),
-                  prefix,
-                  nearest: String(nearestOf(value)[0]),
-                },
+            const rendered = RENDERED_PX(value);
+            /** `md:p-4` → `md:p-sd-16` — variant·부호 접두는 그대로 두고 뒤만 갈아낀다 */
+            const rewrite = (px) =>
+              token.replace(
+                new RegExp(`${escapeRegExp(`${prefix}-${raw}`)}$`),
+                `${prefix}-sd-${px}`,
+              );
+
+            // 두 해석 — 숫자를 px 로 읽는 쪽(값이 바뀐다)과 현재 렌더 값을 지키는 쪽.
+            // 스케일에 없는 해석은 후보에서 빠진다 (sd- 를 붙여도 스타일이 안 생긴다).
+            const asLiteral = ALLOWED.has(value) ? rewrite(value) : null;
+            const asRendered = ALLOWED.has(rendered) ? rewrite(rendered) : null;
+
+            const data = {
+              token,
+              value: raw,
+              actual: String(rendered),
+              asLiteral: asLiteral ?? "",
+              asRendered: asRendered ?? "",
+              fallback: fallbackFor(prefix, rendered),
+            };
+
+            const suggest = [];
+            if (asLiteral) {
+              suggest.push({
+                messageId: "useLiteral",
+                data: { to: asLiteral, actual: String(rendered), value: raw },
+                fix: replaceToken(valueNode, token, asLiteral),
+              });
+            }
+            if (asRendered) {
+              suggest.push({
+                messageId: "useRendered",
+                data: { to: asRendered, actual: String(rendered) },
+                fix: replaceToken(valueNode, token, asRendered),
               });
-              continue;
             }
 
-            const suggestion = token.replace(
-              new RegExp(`${escapeRegExp(`${prefix}-${raw}`)}$`),
-              `${prefix}-sd-${raw}`,
-            );
+            const messageId = asLiteral
+              ? asRendered
+                ? "missingPrefixBoth"
+                : "missingPrefixLiteral"
+              : asRendered
+                ? "missingPrefixRendered"
+                : "missingPrefixNone";
+
             context.report({
               node: valueNode,
-              messageId: "missingPrefix",
-              data: { token, value: raw, actual: String(value * 4), suggestion },
-              fix: replaceToken(valueNode, token, suggestion),
+              messageId,
+              data,
+              suggest,
+              // 마이그레이션용 옵트인 — "숫자 = px" 를 단정하므로 여백 값이 바뀐다
+              ...(unsafeFix && asLiteral
+                ? { fix: replaceToken(valueNode, token, asLiteral) }
+                : {}),
             });
             continue;
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sellmate-design-system-react",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Sellmate Design System — React (TypeScript + Tailwind v4) port",
   "license": "UNLICENSED",
   "keywords": [
@@ -67,6 +67,8 @@
     "format:fix": "prettier --write \"src/**/*.{ts,tsx,css,json,md}\"",
     "check:tokens": "node scripts/check-hardcoded.mjs",
     "check:refs": "node scripts/check-refs.mjs",
+    "check:docs": "node scripts/check-docs-coverage.mjs",
+    "check:docs-refs": "node scripts/check-docs-refs.mjs",
     "version": "node scripts/version.mjs",
     "version:dry": "node scripts/version.mjs --dry-run",
     "clean": "rm -rf dist storybook-static"