@axis-ds/cli 1.7.10 → 1.8.0

package/README.md

@@ -36,7 +36,7 @@ axis list
 - `registryDependencies` 를 재귀로 따라가 `utils`(`cn`) · `agentic-a11y-labels` 같은 lib 항목도 함께 설치합니다. 값이 레지스트리 URL 이면 `<base>/<이름>.json` 형태만 받아 그 이름으로 지금 읽는 레지스트리(원격 또는 CLI 포함본)에서 찾습니다. `<base>` 는 원격을 읽을 때 지금 조회 중인 레지스트리 주소 또는 공개 기본 주소(`https://axis-design-system.pages.dev/r`)이고, CLI 포함본을 읽을 때는 공개 기본 주소입니다. 접두 없는 이름도 받습니다. 다른 호스트 · 경로, 공백 · userinfo(`user@`) · 쿼리가 든 URL, `@ns/이름` · 상대 경로 · `.json` 이 아닌 확장자 · 이름 규칙 위반은 형식 불일치로 봅니다.
 - 배치: Core UI 와 lib 은 `componentsDir`(utils 는 `axis init` 이 쓰는 `componentsDir/utils.ts` 와 같은 위치), Agentic UI 는 `agenticDir`(없으면 `componentsDir` 옆 `agentic` 디렉터리). 레지스트리 형식의 import(`@/registry/<style>/lib/utils` 등)는 설치 위치 기준 상대 경로로 바꾸고, 설치 뒤 그 경로가 실제 파일을 가리키는지 확인합니다.
 - 이미 있는 파일: 내용이 같으면 건너뜀, 다르면 대화형에서는 묻고, `-y` 는 건너뛰며 목록을 알려 주고, `--overwrite` 만 덮어씁니다. 터미널이 아닌 곳(CI · 파이프)에서는 묻지 않고 `-y` 와 같이 건너뜁니다. 출력은 새로 만든 파일 `+`, 덮어쓴 파일 `~ … (덮어씀)`, 같은 내용이라 건너뛴 파일 `=` 입니다. `--overwrite` 는 `registryDependencies` 로 끌려온 파일(예: 고친 `utils.ts`)도 덮어쓰니 출력의 `~` 를 확인하세요.
-- 쓰기 전에 실제 경로(심볼릭 링크를 따라간 위치)가 프로젝트 디렉터리 안인지 확인하고, 밖이면 쓰지 않습니다. 기존 대상 파일이 심볼릭 링크여도 내용이 같거나 `-y` 로 건너뛰면 쓰지 않으므로 건너뜁니다(예: 앱 디렉터리 안의 공용 `utils.ts`, 또는 모노레포의 다른 패키지처럼 프로젝트 밖의 `utils.ts` 에 링크해 둔 경우). 밖을 가리키는 링크는 `= <경로> (같은 내용이라 건너뜀, 링크 대상이 프로젝트 밖)` 처럼 그 사실을 함께 알립니다(rc 0). 상위 디렉터리(`componentsDir` 등)가 밖을 가리키는 링크면 경로 이탈로 거부합니다. 설치 대상이 디렉터리(또는 디렉터리를 가리키는 링크)이거나 기존 파일을 읽지 못하면 이유를 알리고 아무것도 쓰지 않고 rc 1 입니다. 링크를 실제로 덮어써야 할 때(`--overwrite` · 대화형 예, 링크가 프로젝트 안 · 밖 어디를 가리켜도)만 아무것도 쓰지 않고 rc 1 로 알립니다. 덮어써야 하는 일반 파일이 다른 경로와 하드링크로 이어져 있으면(링크 수 2 이상) 쓰기 전에 그 경로와 이유를 알리고 아무것도 쓰지 않은 채 rc 1 로 끝내며, 쓰기 직전에도 연 파일로 한 번 더 확인합니다(내용이 같거나 `-y` 로 건너뛰는 파일은 영향 없음). 덮어쓰기를 묻는 동안 새로 설치할 파일과 같은 이름의 파일이 생기면 그 파일을 덮어쓰지 않고 경로를 알린 뒤 rc 1 로 끝냅니다. 검사와 쓰기 사이의 동시 경합은 사후 검사로 감지합니다: 쓴 파일의 실제 위치가 프로젝트 밖이면 그 파일을 지우지 않고 경로를 알린 뒤 rc 1 로 끝냅니다(그 위치의 파일은 사용자 것일 수 있어 CLI 가 지우지 않음).
+- 쓰기 전에 실제 경로(심볼릭 링크를 따라간 위치)가 프로젝트 디렉터리 안인지 확인하고, 밖이면 쓰지 않습니다. 기존 대상 파일이 심볼릭 링크여도 내용이 같거나 `-y` 로 건너뛰면 쓰지 않으므로 건너뜁니다(예: 앱 디렉터리 안의 공용 `utils.ts`, 또는 모노레포의 다른 패키지처럼 프로젝트 밖의 `utils.ts` 에 링크해 둔 경우). 밖을 가리키는 링크는 `= <경로> (같은 내용이라 건너뜀, 링크 대상이 프로젝트 밖)` 처럼 그 사실을 함께 알립니다(rc 0). 상위 디렉터리(`componentsDir` 등)가 밖을 가리키는 링크면 경로 이탈로 거부합니다. 설치 대상이 디렉터리(또는 디렉터리를 가리키는 링크)이거나 기존 파일을 읽지 못하면 이유를 알리고 아무것도 쓰지 않고 rc 1 입니다. 링크를 실제로 덮어써야 할 때(`--overwrite` · 대화형 예, 링크가 프로젝트 안 · 밖 어디를 가리켜도)만 아무것도 쓰지 않고 rc 1 로 알립니다. 덮어써야 하는 일반 파일이 다른 경로와 하드링크로 이어져 있으면(링크 수 2 이상) 쓰기 전에 그 경로와 이유를 알리고 아무것도 쓰지 않은 채 rc 1 로 끝내고 쓰기 직전에도 연 파일로 한 번 더 확인합니다(내용이 같거나 `-y` 로 건너뛰는 파일은 영향 없음). 덮어쓰기를 묻는 동안 새로 설치할 파일과 같은 이름의 파일이 생기면 그 파일을 덮어쓰지 않고 경로를 알린 뒤 rc 1 로 끝냅니다. 검사와 쓰기 사이의 동시 경합은 사후 검사로 감지합니다: 쓴 파일의 실제 위치가 프로젝트 밖이면 그 파일을 지우지 않고 경로를 알린 뒤 rc 1 로 끝냅니다(그 위치의 파일은 사용자 것일 수 있어 CLI 가 지우지 않음).
 - `package.json` 에 없는 의존성은 lockfile 에 맞춘 설치 명령으로 안내만 합니다(설치는 하지 않음). 안내 명령은 복사해 실행하는 셸 명령이라, 레지스트리의 `dependencies` 값이 패키지 이름(선택적 `@범위`) 형태가 아니면(`;` · `$` · 따옴표 등) 그 원격 응답을 형식 불일치로 보고 CLI 포함본을 씁니다.
   - 앱 `package.json` 다음 워크스페이스 루트 `package.json` 의 선언도 「있음」으로 봅니다. 1.7.9 다음 patch 부터(WI-0095) Yarn Plug'n'Play 에서는 루트 선언을 「있음」으로 보지 않고 미선언과 같게 안내 명령에 넣습니다(앱이 루트에만 선언한 패키지를 해석하지 못해 컴포넌트의 import 가 실패함, MCP `axis.install_component` 도 같음).
 - `axis.config.json` 의 `componentsDir` · `agenticDir` 에 역슬래시(`src\components\ui`)를 적어도 `/` 로 읽습니다.
@@ -124,8 +124,16 @@ axis theme add ontology
   - `brand.activation`: `brand` 가 있을 때 루트 레이아웃(`app/layout.tsx` · `src/app/layout.tsx` · `pages/_app` 등, 그 레이아웃이 import 하는 같은 디렉터리의 `./providers` 한 단계 포함)에 `data-brand` · `setBrand(` · `defaultBrand=` 가 없으면 WARN 입니다(휴리스틱, `ThemeProvider` 단독은 켜는 코드가 아님). 1.6.1 부터 마크업 `data-brand` 와 `ThemeProvider` 만 있고 `setBrand(` · `defaultBrand=` 가 없으면 설치본(없으면 선언) `@axis-ds/theme` 가 1.7.0 미만이거나 판정할 수 없을 때 WARN 입니다(1.6.2 이하는 마운트 때 속성을 지움). 1.7.6 부터 Plug'n'Play 에서 `@axis-ds/theme` 가 워크스페이스 루트에만 선언돼 있으면 「앱이 해석하지 못합니다」 WARN 입니다(Tailwind 3 CommonJS preset 의 `@axis-ds/tokens` 판정도 같음).
   - `tailwind.content`: Tailwind 3 설정 파일이 있고 `componentsDir` 나 선언된 `@axis-ds/ui-react` · `@axis-ds/agentic-ui` 가 있을 때, `content` 의 문자열 glob 이 그 경로를 덮지 않으면 FAIL 입니다(그 경로의 클래스가 생성되지 않음). `content` 를 정적으로 다 읽지 못하면(변수 · 펼침) WARN 입니다. 패키지 경로는 프로젝트 디렉터리부터 상위로 찾은 설치본 위치 기준이라, npm workspaces · pnpm hoisted 처럼 루트에만 설치된 앱은 `../../node_modules/@axis-ds/ui-react/dist/**/*.{js,mjs}` 를 안내합니다(1.7.1 부터, 설치본이 없으면 `./node_modules/...`). `**` 는 `../` 를 넘지 않는 것으로, 절대경로 glob 은 실제 위치와 비교해 판정합니다. 1.7.4 부터 pnpm 기본 레이아웃처럼 앱 설치본이 링크이면 실경로가 같은 상위 설치본(`../../node_modules/...`)과 `.pnpm` 스토어 실경로를 상대 경로로 쓴 glob 도 인정하고, 실경로가 다른 상위 설치본을 가리키면 FAIL 문구에 그 이유를 붙입니다. 상위 경로는 Tailwind 3 가 빌드를 실행한 디렉터리 기준으로 풀리므로 모노레포 루트에서 빌드하면 `content: { relative: true, files: [...] }` 를 쓰세요(판정은 프로젝트 디렉터리에서 빌드한다고 보고 함). 1.7.7 부터 Plug'n'Play(`.pnp.cjs`)에서는 node_modules 가 없으므로 `./node_modules/...` glob 과 넓은 `./**` 를 덮음으로 보지 않고 WARN 으로 알리고(종전 PASS, 실제 빌드는 클래스가 생기지 않음. Tailwind 의 `**` · `*` 는 `.yarn` 처럼 점으로 시작하는 디렉터리를 넘지 않으므로 앱이 Plug'n'Play 루트이고 unplugged 가 있어도 같음), 덮지 않으면 FAIL 은 그대로이되 `./node_modules/...` 대신 `require.resolve` 로 실제 위치를 넣는 동적 형태(정적으로 확인할 수 없어 WARN)를 먼저, `dependenciesMeta` 의 `unplugged: true` 를 대안으로 안내합니다(안내에는 덮지 않은 패키지 이름이 들어감). unplugged 를 설정한 프로젝트는 앱 선언 범위에 맞는 `.yarn/unplugged/*/node_modules/<패키지>` 를 가리키는 glob(상대 · 절대, `.yarn` 을 글자 그대로 쓴 것)을 덮음으로 인정합니다(종료 코드가 1 에서 0 으로 바뀔 수 있음). 컴포넌트 패키지를 워크스페이스 루트에만 선언한 Plug'n'Play 앱은 경로를 안내 · 인정하지 않고 「앱 package.json 에 선언하세요」를 냅니다.
   - `animation`: `@axis-ds/ui-react` 선언이나 `componentsDir` 의 `animate-in` 류 클래스가 있을 때 애니메이션 플러그인(Tailwind 3 `tailwindcss-animate` 선언 + 설치본 + `plugins` 배열 참조, Tailwind 4 는 전역 CSS 선택이 고른 파일(상대 `@import` 로 들여온 하위 파일 포함)의 `@import "tw-animate-css"`)이 없으면 WARN 입니다. 1.6.1 부터 Tailwind 3 은 `plugins` 배열 안의 `require("tailwindcss-animate")` 나 그 패키지를 받은 식별자(`import animate from` · `const animate = require(...)`)만 인정합니다(import 만 있거나 다른 곳의 같은 문자열은 아님). 배열을 정적으로 다 읽지 못하면(펼침 · 단축 속성) 「확인하지 못함」 WARN 입니다. 1.7.6 부터 Tailwind 4 는 CSS 의 줄마다 그 줄의 패키지(`tw-animate-css` · `tailwindcss-animate`)가 선언 · 설치돼 있어야 PASS 이고, 줄은 있는데 선언이나 설치본이 없으면 「애니메이션 플러그인을 쓸 수 없습니다」 WARN 입니다(1.7.5 까지는 줄만 보고 PASS, 실제 빌드는 실패). Plug'n'Play 에서는 플러그인 선언을 앱 `package.json` 에서만 봅니다.
+- 템플릿 규칙 항목(1.8.0 부터, 위 항목들 뒤 맨 끝): `axis.config.json` 의 `template` 이 `ontology-console` 이면 `template.ontology-rules` 항목을 더합니다. 템플릿의 `npm run check:ontology`(`scripts/check-ontology.mjs`)와 같은 다섯 규칙(em-dash · exclamation · one-side-line · card-shadow · palette)을 `app/` · `components/` · `lib/` 에 돌립니다.
+  - axis 에 내장한 판정이고 프로젝트의 스크립트는 실행하지 않습니다(읽기 전용). 판정은 설치한 cli 버전 기준이라, 프로젝트에 복사된 스크립트를 고쳤거나 오래된 템플릿으로 만든 프로젝트는 `npm run check:ontology` 결과와 다를 수 있습니다.
+  - 위반이 없으면 PASS 「파일 N개, 위반 0건」, 있으면 WARN 으로 건수 · 규칙별 수 · 첫 위치(`"파일":줄 규칙`, 파일 · 줄 · 규칙 순으로 가장 앞의 위반)를 냅니다. 프로젝트 `package.json` 에 `check:ontology` script 가 있으면 끝에 「→ 전체 보기: npm run check:ontology」를 붙입니다. 문구에 소스 조각은 싣지 않고, 파일 이름은 글자 · 숫자 · 문장부호 · 기호 · 공백만 남기고 나머지(줄바꿈 · 제어 · 태그 · 폭 없는 문자 등)와 따옴표 · 역슬래시를 `\uXXXX` 로 바꿔 한 줄로 냅니다(120자에서 자름).
+  - 검사한 파일이 0개이거나 디렉터리 · 파일을 읽지 못하면 WARN 「측정 실패」입니다(PASS 가 아님). 위반이 0건이어도 판정하지 못한 파일(256KB 초과 · 깊이 한도 밖 디렉터리 · 클래스 묶음 작업량 상한 초과 · 프로젝트 예산 초과)이 있으면 WARN 「일부 측정 실패」입니다.
+  - 프로젝트 전체 예산은 판정할 파일 4,000개 · 읽는 바이트 합계 16MB · 훑는 디렉터리 항목 50,000개입니다(디렉터리 항목은 대상 밖 확장자 · 디렉터리 · 링크 · 숨김 이름까지 셈). 파일은 `app` → `components` → `lib`, 그 안은 이름순 깊이 우선으로 모으고, 넘으면 그 뒤 파일은 판정하지 않고 「건너뜀: 프로젝트 예산 초과로 측정 중단(파일 4000개 상한)」 · 「(읽기 16MB 상한)」 · 「(디렉터리 항목 50000개 상한)」 가운데 하나를 붙입니다. 위반이 있으면 위반 WARN 에 함께 붙습니다. 예산은 바꿀 수 없습니다(시간 상한은 결과가 기기마다 달라져 두지 않음).
+  - 심볼릭 링크는 실경로가 프로젝트 안일 때만 따라가고(같은 실경로는 한 번, 디렉터리 깊이 32 단계까지), 256KB 를 넘는 파일은 건너뛰고 「건너뜀: …」으로 건수를 알립니다. 프로젝트 밖 · 깨진 링크는 검사 범위 밖이라 건수만 적고 PASS 를 막지 않습니다. 줄 길이 상한은 없고 판정은 파일 크기에 선형인 시간으로 끝납니다.
+  - `template` 이 없거나 문자열이 아니거나 다른 템플릿이면 항목을 만들지 않아 출력이 1.7.x 와 같습니다. 어떤 검사를 돌릴지는 cli 안의 정적 표로 정하고, 원격 템플릿 JSON 의 `checks` 는 읽지 않습니다.
+  - 정규식 휴리스틱이라 변수에 담은 클래스 등은 보지 못하고 오탐이 있을 수 있어 WARN 까지만 냅니다(템플릿 README 「검사의 한계」).
 - FAIL 이 하나라도 있으면 종료 코드 1 로 끝납니다. WARN 만 있으면 0 입니다(1.3.0 부터, 이전에는 결과와 관계없이 0).
-- MCP `axis.check_project` 도 같은 항목 · 문구를 냅니다.
+- MCP `axis.check_project` 도 같은 항목 · 문구를 냅니다(템플릿 규칙 항목은 mcp 1.5.0 부터, 같은 공유 코어).
 
 ## 터미널이 아닌 곳에서 실행 (CI · 파이프 · `</dev/null`)