d3ro-voice/scripts/ci/check-ds-contract.mjs

168 lines
5.4 KiB
JavaScript

// scripts/ci/check-ds-contract.mjs
// TDD v2.0 Phase 2 — @d3ro/ui 디자인 시스템(DS) 컴포넌트 역할·ARIA·토큰·테스트 커버리지 계약 게이트.
//
// 검증 규칙:
// 1. packages/ui/src/components/ds/index.ts 에 export 된 모든 컴포넌트 소스 파일이 존재해야 한다.
// 2. DS 컴포넌트 소스에 하드코딩 hex 색상(#RGB / #RRGGBB)이 없어야 한다.
// 3. 대화형 컴포넌트(PhysicalButton, SegmentControl, TactileBadge)는 명시적 시맨틱/ARIA 계약을 포함해야 한다.
// 4. 장식 지표 컴포넌트(Led, StatRing)는 aria-hidden 을 포함해야 한다.
// 5. packages/ui/__tests__/ds-contract.test.tsx 가 export 된 모든 DS 컴포넌트를 참조해야 하며,
// 스냅샷 단정(toMatchSnapshot / toMatchInlineSnapshot)은 금지한다.
import { existsSync, readFileSync } from 'node:fs'
import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
const dsDir = join(root, 'packages', 'ui', 'src', 'components', 'ds')
const testPath = join(root, 'packages', 'ui', '__tests__', 'ds-contract.test.tsx')
const HEX_COLOR_RE = /#[0-9a-fA-F]{3,8}\b/
const INTERACTIVE_CONTRACTS = {
PhysicalButton: ['<Button', 'aria-hidden'],
SegmentControl: ['role="tablist"', 'role="tab"', 'aria-selected', 'onKeyDown'],
TactileBadge: ["role: 'button'", 'tabIndex: 0', 'onKeyDown']
}
const INDICATOR_ARIA_HIDDEN = ['Led', 'StatRing']
function parseBarrelExports(indexContent) {
const entries = []
const re = /export\s*\{\s*([A-Za-z0-9_]+)\s*\}\s*from\s*['"]\.\/([A-Za-z0-9_-]+)['"]/g
let match
while ((match = re.exec(indexContent)) !== null) {
entries.push({ name: match[1], fileBase: match[2] })
}
return entries
}
function loadSurfaces() {
const barrel = readFileSync(join(dsDir, 'index.ts'), 'utf8')
const entries = parseBarrelExports(barrel)
const components = {}
for (const entry of entries) {
const filePath = join(dsDir, `${entry.fileBase}.tsx`)
components[entry.name] = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null
}
const testContent = existsSync(testPath) ? readFileSync(testPath, 'utf8') : ''
return { barrel, components, testContent }
}
export function validateDsContract(surfaces) {
const errors = []
const entries = parseBarrelExports(surfaces.barrel)
if (entries.length < 10) {
errors.push('ds_barrel_empty')
}
for (const { name } of entries) {
const source = surfaces.components[name]
if (typeof source !== 'string') {
errors.push(`ds_component_missing:${name}`)
continue
}
const strippedComments = source
.replace(/\/\*[\s\S]*?\*\//g, '')
.replace(/\/\/.*$/gm, '')
if (HEX_COLOR_RE.test(strippedComments)) {
errors.push(`ds_hardcoded_hex:${name}`)
}
const requiredSnippets = INTERACTIVE_CONTRACTS[name]
if (requiredSnippets) {
for (const snippet of requiredSnippets) {
if (!source.includes(snippet)) {
errors.push(`ds_interactive_aria_missing:${name}:${snippet}`)
}
}
}
if (INDICATOR_ARIA_HIDDEN.includes(name) && !source.includes('aria-hidden')) {
errors.push(`ds_indicator_aria_hidden_missing:${name}`)
}
const usageRe = new RegExp(`\\b${name}\\b`, 'g')
const matches = surfaces.testContent.match(usageRe) ?? []
// import 1회 + 실제 렌더 최소 1회 = 최소 2회 등장
if (matches.length < 2) {
errors.push(`ds_contract_test_missing:${name}`)
}
}
if (/\btoMatch(?:Inline)?Snapshot\s*\(/.test(surfaces.testContent)) {
errors.push('ds_snapshot_forbidden')
}
if (errors.length > 0) {
throw new Error(`ds_contract_invalid:${errors.join(',')}`)
}
return {
ok: true,
exportedComponents: entries.length
}
}
function expectRejected(baseSurfaces, mutate, expectedCode) {
const clone = structuredClone(baseSurfaces)
mutate(clone)
try {
validateDsContract(clone)
} catch (err) {
if (err instanceof Error && err.message.includes(expectedCode)) return
throw err
}
throw new Error(`ds_contract_self_test_failed:${expectedCode}`)
}
const surfaces = loadSurfaces()
const result = validateDsContract(surfaces)
if (process.argv.includes('--self-test')) {
expectRejected(
surfaces,
(s) => {
s.components.Led = `${s.components.Led}\nconst BAD = '#ff00aa'\n`
},
'ds_hardcoded_hex:Led'
)
expectRejected(
surfaces,
(s) => {
s.components.SegmentControl = s.components.SegmentControl.replace('aria-selected', 'data-selected')
},
'ds_interactive_aria_missing:SegmentControl:aria-selected'
)
expectRejected(
surfaces,
(s) => {
s.components.Led = s.components.Led.replace('aria-hidden', 'data-led')
},
'ds_indicator_aria_hidden_missing:Led'
)
expectRejected(
surfaces,
(s) => {
s.testContent = s.testContent.replaceAll('DoubleBezelCard', 'OtherCard')
},
'ds_contract_test_missing:DoubleBezelCard'
)
expectRejected(
surfaces,
(s) => {
s.testContent = `${s.testContent}\nexpect(html).toMatchSnapshot()\n`
},
'ds_snapshot_forbidden'
)
expectRejected(
surfaces,
(s) => {
s.components.StatRing = null
},
'ds_component_missing:StatRing'
)
result.negativeCases = 6
}
process.stdout.write(`[check:ds-contract] GREEN (${result.exportedComponents} components${result.negativeCases ? `, ${result.negativeCases} self-test cases` : ''})\n`)