dsh-ci-diet 0.1.1 → 0.3.1

package/README.ko.md

@@ -2,9 +2,10 @@
 
 낭비된 GitHub Actions 러너 시간을 찾고, 작고 검토 가능한 패치를 제안합니다.
 
-상태: **알파, npm에 `dsh-ci-diet@0.1.1`로 배포됨**. 계약, 명세, 분석 엔진,
+상태: **알파, `dsh-ci-diet@0.3.1` npm 게시됨**. 계약, 명세, 분석 엔진,
 패치 엔진, CLI, DSH 플러그인 도구, 자체 완결형 HTML 보고서는 구현과 테스트를
-마쳤습니다. DSH Web 클라이언트 화면은 아직 남아 있습니다.
+마쳤습니다. DSH Web 클라이언트는 설정 화면을 제공하고, 보고서·적용 화면은 아직
+남아 있습니다.
 
 ## 하는 일
 
@@ -58,15 +59,43 @@ CI Diet는 두 가지를 읽고 비교합니다.
 
 ## 설치
 
+CLI는 Node `^22.19.0 || >=24.0.0`이 필요합니다. DSH 플러그인은 DSH
+`>=0.2.1-rc.2 <0.3.0-0` 또는 `>=0.2.2-rc.1 <0.3.0-0`이 필요합니다. `0.3.1`
+릴리스는 DSH `0.2.1-rc.2`에서 검증했으며 DSH `0.3.0`은 아직 지원하지 않습니다.
+
+CLI 설치:
+
+```
+npm install --global dsh-ci-diet@0.3.1
+ci-diet --version
+```
+
+전역 설치를 원하지 않으면 `npx dsh-ci-diet@0.3.1`으로 같은 CLI를 실행할 수
+있습니다.
+
+DSH 플러그인 설치:
+
 ```
-npm install --global dsh-ci-diet
-dsh plugin --profile web add dsh-ci-diet
+dsh plugin --profile web add dsh-ci-diet@0.3.1
+dsh --profile web
 ```
 
-플러그인은 기본으로 꺼진 로더 항목 하나를 추가합니다. 이력 동기화를 쓸 때만
-`networkEnabled`를 켜십시오. 전역 설치는 선택 사항입니다. `npx dsh-ci-diet`로
-같은 CLI를 실행할 수 있고, DSH 플러그인은 프로필에 패키지가 있으면 됩니다.
-릴리스 태그는 GitHub에, 같은 버전은 npm `0.1.1`에 있습니다.
+플러그인은 기본으로 꺼진 로더 항목 하나와 **설정 → CI Diet** 페이지를 추가합니다.
+이 페이지에서 분석 규칙, 이력 상한, 저장 공간 한도, 비용 추정, 네트워크 접근,
+상태 디렉터리를 모두 바꿀 수 있습니다. 값은 `ci-diet --config`와 같은 계약 검증과
+기본값을 쓰며, 재시작 없이 다음 도구 호출부터 적용되고 CLI의 설정 파일은 건드리지
+않습니다. 적용 도구가 아직 없어 `localApplyEnabled`는 노출하지 않습니다.
+
+기존 설치 업데이트:
+
+```
+npm install --global dsh-ci-diet@latest
+dsh plugin --profile web add dsh-ci-diet@latest
+```
+
+플러그인을 업데이트한 뒤 DSH를 재시작합니다. `dsh plugin --profile web list`로
+설치된 플러그인 버전을, `ci-diet --version`(또는
+`npx dsh-ci-diet@latest --version`)으로 CLI 버전을 확인할 수 있습니다.
 
 ## 실행
 
@@ -91,20 +120,31 @@ ci-diet revert --change <changeId>       # 백업한 바이트를 복원
 ```
 ci-diet report                 # 저장된 최신 보고서의 텍스트 요약
 ci-diet report --format html --out report.html
+ci-diet diagnose               # Job 이름 매칭과 수집 커버리지 설명
 ci-diet prune                  # 만료된 보고서, 계획, 캐시 정리
 ```
 
 HTML 파일은 자체 완결형입니다. 인라인 CSS만 쓰고 스크립트와 외부 요청이 없습니다.
 읽기 전용이므로 승인은 digest와 nonce 검사가 있는 CLI에 남습니다.
 
+`diagnose`는 저장된 최신 이력을 읽어 GitHub Job 이름이 워크플로 키로 얼마나
+해석됐는지, 어떤 matrix Job이 몇 개 레그로 확장됐는지, 어느 수집 상한 때문에
+커버리지 축이 불완전한지 보여줍니다. 오프라인에서도 동작하며 `--require-complete`를
+쓰면 축이 불완전할 때 종료 코드 `3`으로 끝납니다.
+
+점검용 캐시 힌트도 함께 보여줍니다. 캐시 없이 의존성을 설치하는 Job이나
+lockfile 변경을 따라가지 못하는 리터럴 캐시 키가 대상입니다. 동결된 계약에는
+캐시 규칙 ID가 없으므로 힌트는 발견 항목이나 패치로 이어지지 않습니다.
+
+
 ## 릴리스
 
 `package.json`의 버전과 일치하는 태그를 푸시하면
 `.github/workflows/publish.yml`이 실행됩니다.
 
 ```
-git tag v0.1.1
-git push origin v0.1.1
+git tag v0.3.1
+git push origin v0.3.1
 ```
 
 워크플로는 태그와 `package.json` 버전을 대조하고(`node
@@ -117,13 +157,14 @@ trusted publisher에 이 저장소의 `publish.yml`이 등록되어 있어야
 
 - Node `^22.19.0 || >=24.0.0`
 - `gh` CLI(선택): 실행 이력 조회에만 사용
-- DSH `>=0.2.1-rc.2 <0.3.0`(선택): 플러그인 도구에만 사용
+- DSH `>=0.2.1-rc.2 <0.3.0-0 || >=0.2.2-rc.1 <0.3.0-0`(선택): 플러그인 도구에만
+  사용
 
 ## 개발
 
 ```
 bun install
-node --test "tests/unit/*.test.ts"
+node scripts/test-core.mjs
 node scripts/gen-types.mjs --check
 node scripts/sync-contracts.mjs --check
 bun run typecheck
@@ -151,9 +192,17 @@ tests/unit      네트워크가 필요 없는 빠른 검사
 
 ## 언어
 
-영어가 기본이며 메시지 키의 단일 소스입니다. 한국어는 전체 번역되어 있고, 중국어
-간체는 번역 슬롯으로만 두며 관리자가 생기기 전까지 영어로 대체됩니다. 공개 문서는
-영어이고 README만 한국어로 미러링합니다.
+영어가 기본이며 메시지 키의 단일 소스입니다. CLI, HTML 보고서, DSH 도구 문구는
+영어·한국어·중국어 간체·힌디어·스페인어·프랑스어로 제공하며, 모든 사전이 완역이라
+키가 빠지면 타입 오류가 납니다. 지역 태그는 언어로 해석하고(`hi-IN`, `es-MX`,
+`fr-CA`), 간체가 아닌 중국어 변형은 영어로 대체합니다.
+
+언어 선택 순서는 `--lang`, DSH 언어 설정, `LC_ALL`/`LC_MESSAGES`/`LANG`,
+영어입니다. 보고서는 영어로 저장하고 표시할 때만 번역합니다. 규칙 ID, 오류 코드,
+열거값, 경로, 다이제스트, 수치는 번역하지 않으며 HTML 보고서의 `lang` 속성은
+선택한 언어를 따릅니다. DSH 도구 설명은 플러그인 로드 시점에 고정되므로 DSH
+언어 설정을 바꾸면 다시 로드해야 합니다. 공개 문서는 영어이고 README만 한국어로
+미러링합니다.
 
 ## 문서
 

package/README.md

@@ -2,10 +2,10 @@
 
 Find wasted GitHub Actions runner time and propose small, reviewable patches.
 
-Status: **alpha, published on npm** as `dsh-ci-diet@0.1.1`. The contracts,
+Status: **alpha**, `dsh-ci-diet@0.3.1` is released on npm. The contracts,
 specification, analysis engine, patch engine, CLI, DSH plugin tools, and a
-self-contained HTML report are implemented and tested. The DSH Web client
-screens are still open.
+self-contained HTML report are implemented and tested. The DSH Web client has a
+Settings screen; the report and apply screens are still open.
 
 ## What it does
 
@@ -60,15 +60,43 @@ is not shipped.
 
 ## Install
 
+The CLI needs Node `^22.19.0 || >=24.0.0`. The DSH plugin needs DSH
+`>=0.2.1-rc.2 <0.3.0-0` or `>=0.2.2-rc.1 <0.3.0-0`. Release `0.3.1` was tested
+against DSH `0.2.1-rc.2`; DSH `0.3.0` is not supported yet.
+
+Install the CLI:
+
+```
+npm install --global dsh-ci-diet@0.3.1
+ci-diet --version
+```
+
+If you do not want a global install, `npx dsh-ci-diet@0.3.1` runs the same CLI.
+
+Install the DSH plugin into a profile:
+
+```
+dsh plugin --profile web add dsh-ci-diet@0.3.1
+dsh --profile web
 ```
-npm install --global dsh-ci-diet
-dsh plugin --profile web add dsh-ci-diet
+
+The plugin adds one disabled loader entry and a **Settings → CI Diet** page.
+The page edits every engine setting used by the DSH tools: analysis rules, history
+caps, storage limits, the cost estimate, network access, and the state directory.
+Values use the same contract validation and defaults as `ci-diet --config`, apply
+to the next tool call without a restart, and never rewrite the CLI's own config.
+`localApplyEnabled` is not exposed because there is no apply tool yet.
+
+Update an existing install:
+
+```
+npm install --global dsh-ci-diet@latest
+dsh plugin --profile web add dsh-ci-diet@latest
 ```
 
-The plugin adds one disabled loader entry; enable `networkEnabled` only if you
-want history sync. Installing the package globally is optional: `npx dsh-ci-diet`
-runs the same CLI, and the DSH plugin only needs the package in the profile.
-Release tags are on GitHub; the matching npm version is `0.1.1`.
+Restart DSH after updating the plugin. `dsh plugin --profile web list` shows the
+installed plugin version, and `ci-diet --version` (or
+`npx dsh-ci-diet@latest --version`) shows the CLI version.
 
 ## Run it
 
@@ -85,14 +113,23 @@ ci-diet revert --change <changeId>       # restores the backed-up bytes
 `plan` refuses to write when the finding is not patch-eligible, when coverage
 does not allow a write, or when the policy snapshot a rule depends on is stale.
 CD005 needs `--job` and `--minutes`; CD008 needs `--job` and `--step`, plus
-`--claims artifact-purpose:temporary,consumer-min-days:7`. Nothing is committed,
-pushed, or applied without the explicit `approve` step.
+`--claims artifact-purpose:temporary,consumer-min-days:7`. The command prints the
+proposed lines as a diff, and `ci-diet plans --plan <planId>` shows a saved plan
+again. Nothing is committed, pushed, or applied without the explicit `approve`
+step.
+
+`--config <file>` merges a partial JSON configuration over the built-in defaults
+for any command, so a repository can lower the workflow size limit or the
+storage quota without code changes. The merged document is validated against
+the frozen contract before the command runs; an unreadable or invalid file
+exits `2`. Relative paths resolve against the effective `--cwd`.
 
 ## Read a report
 
 ```
-ci-diet report                 # text summary of the latest stored report
+ci-diet report                 # text summary for this repository
 ci-diet report --format html --out report.html
+ci-diet diagnose               # explain job-name attribution and collection coverage
 ci-diet prune                  # drop expired reports, plans, and cache entries
 ```
 
@@ -100,14 +137,24 @@ The HTML file is self-contained: inline CSS, no scripts, no external requests.
 It is read-only, so approvals stay in the CLI where the digest and nonce checks
 live.
 
+`diagnose` reads the latest stored history and reports how many GitHub job
+names resolved to workflow keys, which matrix jobs expanded, and which
+collection caps left a coverage axis incomplete. It is read-only and works
+offline; `--require-complete` exits `3` when any axis is incomplete.
+
+It also lists advisory cache hygiene hints: a dependency install with no cache,
+and a literal cache key that cannot follow the lockfile. The frozen contract has
+no cache rule id, so hints never become findings or patches.
+
+
 ## Releasing
 
 Pushing a tag that matches the version in `package.json` triggers
 `.github/workflows/publish.yml`:
 
 ```
-git tag v0.1.1
-git push origin v0.1.1
+git tag v0.3.1
+git push origin v0.3.1
 ```
 
 The workflow compares the tag with `package.json` (`node
@@ -120,13 +167,14 @@ package's trusted publisher must name `publish.yml` for this repository.
 
 - Node `^22.19.0 || >=24.0.0`
 - `gh` CLI, optional, only for execution history
-- DSH `>=0.2.1-rc.2 <0.3.0`, optional, only for the plugin tools
+- DSH `>=0.2.1-rc.2 <0.3.0-0 || >=0.2.2-rc.1 <0.3.0-0`, optional, only for
+  the plugin tools
 
 ## Development
 
 ```
 bun install
-node --test "tests/unit/*.test.ts"
+node scripts/test-core.mjs
 node scripts/gen-types.mjs --check
 node scripts/sync-contracts.mjs --check
 bun run typecheck
@@ -154,10 +202,19 @@ tests/unit      fast checks that need no network
 
 ## Languages
 
-English is the default and the source of truth for message keys. Korean is
-fully translated. Simplified Chinese is a translation slot that falls back to
-English until someone maintains it. Public documentation is English, with a
-Korean README mirror.
+English is the default and the source of truth for message keys. The CLI, the
+HTML report, and DSH tool text ship in English, Korean, Simplified Chinese,
+Hindi, Spanish, and French; every dictionary is complete, so a missing key is a
+type error. Regional tags resolve by language (`hi-IN`, `es-MX`, `fr-CA`), and
+Chinese variants that are not Simplified fall back to English.
+
+Language selection is an explicit `--lang`, then the DSH locale preference,
+then `LC_ALL`/`LC_MESSAGES`/`LANG`, then English. Reports are stored in
+English and translated only when displayed: rule ids, error codes, enum values,
+paths, digests, and numbers stay untranslated, and the HTML report sets its
+`lang` attribute to the selected locale. DSH tool descriptions are captured at
+plugin load, so changing the DSH language preference needs a reload. Public
+documentation is English, with a Korean README mirror.
 
 ## Documentation
 

package/client/index.d.ts

@@ -0,0 +1,3 @@
+/** DSH Web client half for the CI Diet settings section. */
+declare const plugin: { readonly inject: readonly string[]; apply(ctx: unknown): void };
+export default plugin;