@things-factory/figure-ui 10.1.5 → 10.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-ui",
-  "version": "10.1.5",
+  "version": "10.1.7",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -26,8 +26,8 @@
     "clean": "npm run clean:server && npm run clean:client"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.12",
-    "@hatiolab/things-scene": "^10.1.6",
+    "@hatiolab/figure-model": "^0.1.15",
+    "@hatiolab/things-scene": "^10.1.10",
     "@material/web": "^2.0.0",
     "@operato/data-grist": "^10.0.0",
     "@operato/graphql": "^10.0.0",
@@ -36,8 +36,9 @@
     "@operato/p13n": "^10.0.0",
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/figure-service": "^10.1.4",
+    "@operato/utils": "^10.0.0",
+    "@things-factory/figure-service": "^10.1.7",
     "three": "^0.185.1"
   },
-  "gitHead": "d7e60939822ef18e5311311746b2abd28f169173"
+  "gitHead": "9a036f83f5751f9e4af9180e9a0018f716a4ba27"
 }

package/test/i18n-prefix-guard.test.ts

@@ -0,0 +1,171 @@
+/*
+ * **번역 키는 모듈 접두 아래 있어야 한다** (2026-09-10).
+ *
+ * ── 무엇이 있었나 ───────────────────────────────────────────────────────────
+ * things-factory 는 모듈마다 `translations/*.json` 을 두고 **한 평면에 병합한다.** 같은 키가
+ * 여럿이면 마지막이 이기고 아무 경고도 없다. 그래서 내 파일을 읽어도 화면에 뜨는 값을 알 수
+ * 없다 — 내가 적은 값이 아니라 이긴 값이 뜬다.
+ *
+ * 실제로 그랬다. figure 앱의 발행 단추가 「배포」로 떴다(board-ui 의 `button.release` 가 이겼다).
+ * 그때 figure 의 266개 키 중 아홉이 **다른 뜻으로** 겹쳐 있었다 — 모델러가 자기 부품을 board 의
+ * 낱말인 「품목」이라 부르고 있었고 아무것도 그것을 말해 주지 않았다.
+ *
+ * ── 규약 ────────────────────────────────────────────────────────────────────
+ * `<모듈>.<통>.<이름>` 이다. board-ai 가 세웠다 — 그쪽 키 58개 전부가 그 모양이다.
+ *
+ *   figure.label.anchor      ✓
+ *   label.anchor             ✗  일반 통에 남으면 다음 모듈과 또 부딪힌다
+ *   button.release-figure    ✗  뒤에 붙여도 `button.` 통 안이다
+ *
+ * ── 내 것이 아닌 통 ────────────────────────────────────────────────────────
+ * `field.` 는 shell 이 정의하는 공용 칸 이름(`updated_at` · `updater` · `thumbnail`)이다. 목록
+ * 화면들이 같은 낱말로 같은 뜻을 쓰므로 내 접두 아래로 옮기면 **figure 만 다른 말을 한다.**
+ * 읽기만 하고 소유하지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+import { CHANNEL_PATHS, CLIP_DRIVES, INTERPOLATIONS } from '@hatiolab/figure-model'
+
+const HERE = fileURLToPath(new URL('.', import.meta.url))
+const TRANSLATIONS = join(HERE, '../translations')
+const CLIENT = join(HERE, '../client')
+
+/** 남이 소유한 통. 읽기만 한다. */
+const NOT_MINE = ['field.']
+
+function screens(dir: string, into: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) screens(path, into)
+    else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) into.push(path)
+  }
+  return into
+}
+
+const FILES = screens(CLIENT)
+const KO = JSON.parse(readFileSync(join(TRANSLATIONS, 'ko.json'), 'utf-8')) as Record<string, string>
+
+test('번역 파일의 모든 키가 figure. 접두 아래 있다', () => {
+  const loose = Object.keys(KO).filter(key => !key.startsWith('figure.'))
+
+  assert.deepEqual(
+    loose,
+    [],
+    `일반 통에 남은 키다. 다른 모듈이 같은 이름을 쓰면 조용히 진다:\n  ${loose.join('\n  ')}`
+  )
+})
+
+test('통은 label · text · button · title 넷이다 — 모듈 접두 다음 마디', () => {
+  const buckets = new Set(Object.keys(KO).map(key => key.split('.')[1]))
+  const odd = [...buckets].filter(one => !['label', 'text', 'button', 'title'].includes(one!))
+
+  assert.deepEqual(odd, [], `모르는 통: ${odd.join(' · ')}`)
+})
+
+test('화면이 부르는 키가 전부 접두를 지나간다', () => {
+  /*
+    문자열을 통째로 적은 자리만 본다. `'figure.button.' + name` 처럼 이어 붙이는 자리는 앞머리가
+    이미 접두를 지나가므로 같은 정규식에 걸린다.
+  */
+  const loose: string[] = []
+  for (const path of FILES) {
+    const text = readFileSync(path, 'utf-8')
+    for (const [at, line] of text.split('\n').entries()) {
+      const call = /i18next\.t\(\s*['"`]([\w.-]+)/.exec(line)
+      if (!call) continue
+      const key = call[1]!
+      if (key.startsWith('figure.') || NOT_MINE.some(one => key.startsWith(one))) continue
+      loose.push(`${path.slice(CLIENT.length + 1)}:${at + 1}  ${key}`)
+    }
+  }
+
+  assert.deepEqual(loose, [], `접두 없이 부르는 자리다:\n  ${loose.join('\n  ')}`)
+})
+
+test('통째로 부르는 키가 번역 파일에 있다 — 없으면 화면에 키가 그대로 뜬다', () => {
+  const missing: string[] = []
+  for (const path of FILES) {
+    const text = readFileSync(path, 'utf-8')
+    for (const match of text.matchAll(/(?:i18next\.t|help)\(\s*['"`](figure\.[\w.-]+)['"`]/g)) {
+      const key = match[1]!
+      /*
+        앞머리는 통째 키가 아니다. `i18next.t('figure.label.role-' + one)` 처럼 이어 붙이는
+        자리가 같은 정규식에 걸리고, 그것은 `-` 나 `.` 로 끝난다. 그 값들까지 전수로 보려면
+        코드에서 열거 배열을 읽어야 하므로 여기서는 짝이 갈린 것만 아래에서 못 박는다.
+      */
+      if (/[-.]$/.test(key)) continue
+      if (!(key in KO)) missing.push(`${path.slice(CLIENT.length + 1)}  ${key}`)
+    }
+  }
+
+  assert.deepEqual(missing, [], `부르는 키가 번역에 없다:\n  ${missing.join('\n  ')}`)
+})
+
+/*
+  이어 붙이는 자리는 값을 코드에서 읽어야 알 수 있어 여기서 전수 검사하지 않는다. 대신 **통이
+  갈린 짝**을 못 박는다 — 사다리 이름은 `label`, 그 설명은 `text` 다. 한 번 어긋났고, 그때
+  사다리 설명 세 줄이 화면에 키로 떴다. 넓은 앞머리(`figure.text.`)가 미사용 검사를 덮어
+  통과시켰다.
+*/
+test('★ 통이 갈린 짝 — 사다리 이름과 설명', () => {
+  for (const rung of ['none', 'hold', 'flow']) {
+    assert.ok(`figure.label.rung-${rung}` in KO, `figure.label.rung-${rung} 이 없다`)
+    assert.ok(`figure.text.rung-${rung}-note` in KO, `figure.text.rung-${rung}-note 이 없다`)
+  }
+
+  const source = readFileSync(join(CLIENT, 'modeller/figure-capabilities.ts'), 'utf-8')
+  assert.ok(source.includes('figure.label.rung-${which}'), '사다리 이름을 label 통에서 찾지 않는다')
+  assert.ok(source.includes('figure.text.rung-${which}-note'), '사다리 설명을 text 통에서 찾지 않는다')
+})
+
+/*
+  애니메이션 탭도 열거 값을 키에 이어 붙인다. 사다리와 **같은 모양의 함정**이라 같은 못을 박는다.
+
+  갈린 통이 둘이다 — 구동은 이름(`label`)과 설명(`text.…-note`), 경로는 이름(`label`)과
+  단위 설명(`text.…-unit`). 한쪽만 넣으면 화면에 키가 그대로 뜨고, 넓은 앞머리가 위의
+  미사용 검사를 덮어 통과시킨다.
+
+  열거 값을 여기 다시 적지 않고 형식에서 읽는다. 적어 두면 형식에 값을 하나 더할 때
+  검사가 조용히 통과한다.
+*/
+test('★ 열거 값마다 짝이 다 있다 — 구동 · 경로 · 보간', () => {
+  const missing: string[] = []
+  const want = (key: string) => {
+    if (!(key in KO)) missing.push(key)
+  }
+
+  for (const drive of CLIP_DRIVES) {
+    want(`figure.label.drive-${drive}`)
+    want(`figure.text.drive-${drive}-note`)
+  }
+  for (const path of CHANNEL_PATHS) {
+    want(`figure.label.path-${path}`)
+    want(`figure.text.path-${path}-unit`)
+  }
+  for (const one of INTERPOLATIONS) {
+    want(`figure.label.interpolation-${one}`)
+  }
+
+  assert.deepEqual(missing, [], `이어 붙여 부르는 키가 번역에 없다:\n  ${missing.join('\n  ')}`)
+})
+
+test('★ 애니메이션 탭이 그 통에서 찾는다 — 이름은 label, 설명은 text', () => {
+  const source = readFileSync(join(CLIENT, 'modeller/figure-animations.ts'), 'utf-8')
+
+  assert.ok(source.includes("'figure.label.drive-' + drive"), '구동 이름을 label 통에서 찾지 않는다')
+  assert.ok(source.includes("'figure.text.drive-'"), '구동 설명을 text 통에서 찾지 않는다')
+  assert.ok(source.includes("'figure.label.path-' + path"), '경로 이름을 label 통에서 찾지 않는다')
+  assert.ok(source.includes("'figure.text.path-' + channel.path + '-unit'"), '단위 설명을 text 통에서 찾지 않는다')
+})
+
+test('★ 이 가드가 실제로 읽고 있다 — 0이면 검사가 죽은 것이다', () => {
+  assert.ok(Object.keys(KO).length > 250, `읽은 키가 ${Object.keys(KO).length}개다`)
+  assert.ok(FILES.length > 10, `읽은 화면이 ${FILES.length}개다`)
+
+  // 한 번 걸렸던 모양을 넣어 본다.
+  assert.ok(!/^figure\./.test('label.anchor'), '접두 없는 키를 지금은 통과시킨다')
+})

package/test/korean-register-guard.test.ts

@@ -0,0 +1,83 @@
+/*
+ * **화면 한국어에는 비유·구어·의인화를 쓰지 않는다** (2026-09-10).
+ *
+ * ── 무엇이 있었나 ───────────────────────────────────────────────────────────
+ * 성숙도 탭의 빈 화면이 「무게와 점수를 재는 자리입니다」라고 적혀 있었다. 사용자가 물었다 —
+ * 「무게가 뭐야 저울 달아? 점수는 뭔데 무슨 점수?」 이 형식에는 질량도 물리도 없다. 그 묶음이
+ * 표시하는 것은 삼각형 수 · draw call · 서로 다른 형상 · 서로 다른 재질, 전부 그리는 값이다.
+ * 3D 저작 도구에서 「무게」는 물리 속성으로 읽힌다. 안 가르치는 정도가 아니라 틀린 것을 가르쳤다.
+ *
+ * 고치면서 또 걸렸다. 「재어 … 말해 주는 자리입니다」 — 「잰다」는 구어이고(측정한다), 화면이
+ * 「말해 준다」는 의인화다. 한 번 지적받고 고친 문장에서 두 번 더 걸렸다.
+ *
+ * ── 왜 검사로 만드나 ────────────────────────────────────────────────────────
+ * 규칙은 이미 있다. 지키지 못한 것은 규칙을 몰라서가 아니라, 초안을 쓸 때 확인하지 않고 지적을
+ * 받은 뒤에 확인했기 때문이다. 같은 자리에서 반복되는 것은 주의력에 맡겨 둔 탓이므로 검사로
+ * 옮긴다. 이 검사는 매번 실행되고 내 주의력은 그렇지 않다.
+ *
+ * ── 무엇을 막나 ─────────────────────────────────────────────────────────────
+ * 화면에 그대로 나가는 글, 즉 `translations/*.json` 의 값만 본다. 코드 주석과 대화는 같은 규칙을
+ * 받지만 여기서 막지 않는다 — 화면 문구가 고객에게 보이는 것이라 우선순위가 다르다.
+ *
+ * 목록으로 전부 막을 수는 없다. 여기 있는 것은 **실제로 이 저장소에서 걸린 것들**이고, 새로
+ * 걸릴 때마다 한 줄씩 늘린다. 목록이 규칙 자체는 아니다 — 규칙은
+ * `feedback_korean_plain_technical` 이고, 판단 기준은 「그 낱말이 기술 문서에 인쇄돼 있는 것을
+ * 본 적이 있는가」다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const KO = fileURLToPath(new URL('../translations/ko.json', import.meta.url))
+
+/** 걸러낼 표현과, 그 자리에 쓸 말. */
+const BANNED: readonly { readonly pattern: RegExp; readonly instead: string; readonly why: string }[] = [
+  { pattern: /잽니다|잰다|재는 자리|재어|재 봅니다/, instead: '측정합니다 · 측정한다', why: '구어' },
+  { pattern: /말해 주|알려 주는 자리|가르쳐 줍니다/, instead: '표시합니다', why: '화면을 사람처럼 말하게 한다' },
+  { pattern: /무게/, instead: '그리는 비용 · 삼각형 수', why: '3D 도구에서 물리 질량으로 읽힌다' },
+  { pattern: /앉습니다|앉는다|앉을 자리/, instead: '놓습니다 · 놓을 자리', why: '의인화' },
+  { pattern: /던집니다|던진다/, instead: '오류를 냅니다', why: '목적어가 없어 문장이 성립하지 않는다' },
+  { pattern: /먹습니다|먹는다|먹히지/, instead: '소비합니다', why: '구어' },
+  { pattern: /훑습니다|훑는다/, instead: '순회합니다', why: '구어' },
+  { pattern: /갈립니다|갈린다/, instead: '달라집니다', why: '구어' },
+  { pattern: /건드립니다|건드린다|손봅니다/, instead: '수정합니다', why: '구어' },
+  { pattern: /못 박|박습니다/, instead: '명시합니다', why: '구어' },
+  { pattern: /굴러갑니다|굴러간다/, instead: '실행됩니다', why: '구어' },
+  { pattern: /샙니다|샌다|굳습니다/, instead: '누락됩니다 · 고정됩니다', why: '구어' },
+  { pattern: /뭉툭/, instead: '부정확 · 모호', why: '구어' },
+  { pattern: /오버헤드/, instead: '느려집니다 · 비용', why: '무엇이 어떻게 되는지 말하지 않는다' }
+]
+
+test('화면 문구에 비유·구어·의인화가 없다', () => {
+  const ko = JSON.parse(readFileSync(KO, 'utf-8')) as Record<string, string>
+
+  const caught: string[] = []
+  for (const [key, value] of Object.entries(ko)) {
+    for (const { pattern, instead, why } of BANNED) {
+      if (pattern.test(value)) {
+        caught.push(`${key}\n      "${value}"\n      ${why} → ${instead}`)
+      }
+    }
+  }
+
+  assert.deepEqual(caught, [], `화면에 나가는 글이다. 고치고 나서 통과시킨다.\n\n    ${caught.join('\n\n    ')}\n`)
+})
+
+/*
+  검사가 죽으면 조용히 통과한다. 파일을 못 읽거나 목록이 비면 위 시험은 언제나 초록이고,
+  그것을 「문제가 없다」로 읽게 된다.
+*/
+test('★ 이 가드가 실제로 문구를 읽고 있다 — 0이면 검사가 죽은 것이다', () => {
+  const ko = JSON.parse(readFileSync(KO, 'utf-8')) as Record<string, string>
+
+  assert.ok(Object.keys(ko).length > 100, `읽은 문구가 ${Object.keys(ko).length}개다`)
+  assert.ok(BANNED.length > 10, '목록이 비었다')
+
+  // 실제로 걸리는 문장을 넣어 본다. 안 걸리면 정규식이 죽은 것이다.
+  const sample = '무게와 점수를 재는 자리입니다'
+  assert.ok(
+    BANNED.some(({ pattern }) => pattern.test(sample)),
+    '한 번 걸렸던 문장을 지금은 못 잡는다'
+  )
+})