docs: add build-error reference with verified fixes

[owjs3901]

Refs #693 (K 필수: 빌드 오류 목록과 해결 방법). #732 위에 쌓은 docs/build-errors 브랜치이며, base는 main입니다. #732가 먼저 병합되어야 합니다.

요약

• /docs/build-errors에 API별 빌드 오류 참조를 추가합니다. 메시지 패턴, 실패하는 최소 예제, 빌드가 처리할 수 없는 이유, 처리 가능한 수정 예제를 함께 제공합니다.
• 문서 메뉴, 한계 문서, 빌드 오류를 언급하는 영문/국문 README와 ESLint 규칙 문서에서 새 페이지로 연결합니다.
• 정적 export 경로 목록과 페이지/메뉴/한계 문서 링크 회귀 테스트를 추가합니다.
• 긴 코드 블록이 문서 flex item을 늘리지 않도록 docs/layout.tsx의 문서 본문에 minW={0}을 추가했습니다. 코디네이터가 승인한 문서 렌더링 수정이며 기존 레이아웃/스타일 시스템은 유지합니다.
• W19 변경은 문서와 문서 경로 테스트뿐입니다. Rust/플러그인 동작은 변경하지 않았으며, 기본 브랜치의 Rust lint 수정은 #732에 속합니다.

동작

Style props, css/globalCss/keyframes, styled, Emotion css prop/ClassNames, theme reads, imports/barrels, vanilla-extract, StyleX, plugins/config를 별도 섹션으로 구성합니다. 같은 메시지 패턴은 적용되는 API를 명시해 묶고, 서로 다른 요구사항은 생략하지 않습니다.

오류 메시지는 실제 WASM 프로브 출력에서 가져왔습니다. 파일/줄/열/문제가 된 코드 등 변하는 자리만 플레이스홀더로 표시합니다. 스타일 진단과 설정/모듈 평가 오류, ESLint 진단, 빌드 플러그인이 빠졌을 때의 런타임 placeholder 오류를 구분합니다.

조사한 소스

모든 소스는 아래 원격 브랜치의 해당 커밋에서 읽었습니다. #730은 #706부터 #729까지의 스택을 포함합니다.

브랜치	PR	커밋
origin/main	기준	a935315c
origin/fix/selectors	#702	d94ef3c6
origin/fix/compat-imports	#709	4a6ee3a2
origin/fix/styled-props	#711	e2cfa67b
origin/fix/theme-reads	#713	53bdbc20
origin/fix/emotion-css	#716	9b2a04a3
origin/fix/emotion-fallback-arrays	#717	bb86b80d
origin/fix/vanilla-extract-companions	#718	7866e4f3
origin/fix/nested-css-results	#719	001a9816
origin/fix/emotion-component-selectors	#730	d44950f7
origin/fix/imported-styled-definitions	#736	7df41c06
origin/fix/barrel-and-namespace-imports	#737	10ec6113
origin/fix/imports-follow-aliases	#742	4830601d
origin/fix/emotion-rule-numbers-and-mixins	#740	050c6862
origin/fix/local-style-objects	#745	734fd16f
origin/fix/scoped-compiled-names	#750	29812f37
origin/fix/tailwind-classes	#705	c4a62b68
origin/feat/tailwind-v4-complete	#749	8104fdec
origin/fix/types-match-build	#738	d0028a89
origin/fix/eslint-alias-rules	#735	32c30074

libs/extractor/src/utils.rs, css_prop.rs, class_arguments.rs, barrel.rs, barrel/*, imported_styled.rs, extractor/*.rs, vanilla_extract.rs, import_alias_visit.rs, packages/*/src의 진단과 호출 지점을 조사했습니다. 설정 검증 메시지는 WASM 경계와 libs/sheet/src/theme.rs도 확인했습니다.

새로 생기는 오류

없습니다. 이 PR은 위 구현 브랜치의 오류를 설명할 뿐, 새로운 오류나 런타임 동작을 만들지 않습니다. no-runtime-read는 같은 잘못된 런타임 읽기를 빌드 전에 알리는 ESLint 진단이며, 그 메시지의 끝 마침표까지 별도로 검증했습니다.

남는 한계

• 다음 네 소스는 이번 작업의 pending sources입니다. 기다리거나 존재하지 않는 오류를 추측하지 않았고, 푸시된 뒤 후속 작업으로 섹션을 확장합니다: fix/plugin-core (W20: MDX/resolver/config), fix/next-coordinator (W21: coordinator/completeness), fix/composition-rest (W27: @layer/composition), fix/atom-hoist-names (W29).
• Parser/모듈 로더/Boa 실행/테마 등록 위치 누락은 수정 중인 알려진 갭입니다. 관찰한 메시지는 Parser panicked, Cannot load '<specifier>' without a module resolver, Cannot resolve '<specifier>' from '<importer>', JS execution error: ... (unknown at :<line>:<column>) 및 위치 없는 테마 등록 메시지입니다. 코디네이터 지시에 따라 공개 페이지에서는 제외하고, located-diagnostics/설정 후속 수정 뒤 추가합니다.
• 잘못된 devup.json이 빈 설정으로 대체되거나 Vite/Webpack/Rsbuild가 테마 검증 실패를 로그만 남기는 동작도 수정 중인 갭입니다. 공개 페이지에서 최종 동작으로 안내하지 않으며 W20/W21 이후 설정 후속 수정으로 처리합니다.
• 범위 밖 StyleX 문제도 실제 프로브로 확인해 코디네이터에게 전달했습니다: dynamic arrow 기본값이 누락되고, async arrow가 오류 없이 동기 스타일로 바뀝니다. 성공한 프로브를 실패 예제로 꾸며 넣지 않았습니다.
• .css.ts의 Date.now()도 같은 입력에서 서로 다른 CSS를 생성함을 확인했습니다 (width:1791085877664px, width:1791085902828px). evaluator 후속 수정으로 위치 있는 빌드 오류가 될 예정이며 공개 페이지에는 현재 동작을 한계로 적지 않습니다.
• 개별 소스 브랜치의 WASM을 분리해 빌드했습니다. 모든 미병합 PR의 동작을 합친 최종 바이너리를 검증했다고 주장하지 않습니다.

검증

• bun install, 현재 작업 트리의 WASM 재빌드, 루트 bun run build 통과.
• 분리된 소스 snapshot과 전용 target으로 fix(extractor): scope nested selectors, keep content strings and reject selectors that select nothing #702/fix(extractor): map literal-key theme reads to variables and reject unmapped ones #713/feat(extractor): alias @emotion/css css, cx, keyframes and injectGlobal #716/fix(extractor): report vanilla-extract recipes and sprinkles imports under the css alias #718/fix(extractor): resolve compiled names by lexical binding #750 WASM 빌드 통과.
• 조사 단계에서 349개 실패/수정 쌍과 5개 실제 Next loader callback 쌍을 검증했습니다. 공개 페이지에 남긴 238개 실제 표시 코드 블록을 정리/포맷한 뒤 모두 다시 프로브해 예상 실패/성공을 확인했습니다. 수정 중인 갭의 예제는 별도 근거 파일에만 남깁니다.
• cargo fmt --all, cargo +1.99 clippy --workspace --all-targets --message-format short -- -D warnings, cargo test --workspace 통과.
• bun test: 5474 pass, 0 fail, 함수/줄 커버리지 100%.
• Windows 로컬 tarpaulin: 테스트 통과, 97.97% (13311/13587; 커밋 훅 실행마다 97.97~97.98%). 미커버 줄은 모두 W19가 변경하지 않은 Rust 코드입니다. 최종 publishability는 CI의 Linux --fail-under 100 결과로 확인합니다.
• 변경된 경로 manifest/Playwright 테스트의 strict TypeScript 검사 통과. LSP는 설치되어 있지 않으며 설치를 이전에 거절한 상태라, clean-LSP라고 주장하지 않습니다.
• bun lint 통과: 기존 경고 2개 외 없음. 새 페이지의 의도적으로 실패하는 코드는 tsx-error fence로 구분하고, ESLint가 아닌 실제 WASM으로 검증합니다. 성공 예제는 일반 TSX fence로 lint합니다.
• landing vinext와 Next 빌드 통과, 두 결과 모두 /docs/build-errors를 export합니다. 새 페이지/메뉴/링크 테스트 4개 통과, Next의 전체 정적 경로 manifest도 통과(총 5개 focused test).
• 실제 Chromium QA: 새 페이지에서 375/768/1280px 모두 scrollWidth == viewportWidth, 페이지 오류 0개. Box/css 기존 문서의 1280px 전후 스크린샷 및 기존 5px overflow 측정은 유지됩니다.
• Windows vinext의 speculative prerender가 변경하지 않은 breakpoints/zero-runtime 경로를 일부 실행에서 누락하는 현상은 범위 밖 관찰입니다. manifest 기대값은 약화하지 않았으며 Linux CI 결과로 최종 확인합니다.
• CI (헤드 2b6c03ec): run 37192926790 success — publish(lint, tarpaulin --fail-under 100, bun test, landing e2e), landing-next-e2e, vinext-rsc-css-e2e, benchmark 모두 통과.

실제 프로브 출력 예시

<file>:2:21: `css()` cannot use `width` at build time: its values must be literals, theme tokens or constants, or be computed from them
<file>:2:36: `css` on `<div>` cannot use `getStyles()` at build time: it must be a style object, CSS text, a class `css()` gives, or a function of the theme giving one, or an array or condition of them
<file>:2:61: `css` on `<div>` cannot use `rules` at build time: a mixin must stand outside nested rules, where the parts it composes with can be split
<file>:2:9: `css` is read at runtime, where it does not exist: the build compiles it only where it is called or rendered

App.tsx:2:9: devup/no-runtime-read: `css` is read at runtime, where it does not exist: the build compiles it only where it is called or rendered.

[github-actions]

Changepacks

@devup-ui/components@0.1.60 → 0.1.61 - packages/components/package.json

Patch

• Auto-update: depends on '@devup-ui/react' via a local workspace dependency

@devup-ui/eslint-plugin@1.0.22 → 1.0.23 - packages/eslint-plugin/package.json

Patch

• The @devup-ui/react README and the css-utils-literal-only rule docs link their mention of build errors to the new Build Errors reference (https://devup-ui.com/docs/build-errors), which lists the build errors grouped by API; the docs sidebar lists the page after Supported Syntax & Limitations, whose Build errors section links to it. Documentation only: no new build errors

@devup-ui/react@1.0.44 → 1.0.45 - packages/react/package.json

Patch

• The @devup-ui/react README and the css-utils-literal-only rule docs link their mention of build errors to the new Build Errors reference (https://devup-ui.com/docs/build-errors), which lists the build errors grouped by API; the docs sidebar lists the page after Supported Syntax & Limitations, whose Build errors section links to it. Documentation only: no new build errors
• The README no longer claims every CSS-in-JS pattern compiles: it describes what the build compiles and that anything it cannot know is a CSS variable or a located build error, and links the new Supported Syntax & Limitations page, which lists what compiles, the style override rules (where a later part wins and where the CSS cascade decides), Baseline 2024 browser support, that a component taking the css prop must pass className and style on, the runtime-only APIs and how each is handled, and the known limitations

@devup-ui/reset-css@1.0.31 → 1.0.32 - packages/reset-css/package.json

Patch

• Auto-update: depends on '@devup-ui/react' via a local workspace dependency

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
bindings/devup-ui-wasm/src/lib.rs	100.00% <ø> (ø)
libs/css/src/theme_tokens.rs	100.00% <ø> (ø)
libs/extractor/src/lib.rs	100.00% <ø> (ø)
libs/extractor/src/tailwind.rs	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.