Files
clean-architecture-frontend…/config/repository-layout.json
T
DongHyeonka 7ed0af3d29 ci(gates): merge job 셋이 의존성 캐시에서 설치를 시작하고 main만 저장한다
문제: merge job 셋은 runner의 새 컨테이너에서 매번 Node(GitHub
다운로드), corepack의 pnpm, 패키지 404개를 내려받고, pnpm 11은 lockfile
542개 항목의 공급망 정책을 레지스트리에 물어 검증한다. run 169에서 job마다
setup-node 11~18초, 설치 12~29초였고 설치 시간의 대부분은 정책 검증의
메타데이터 요청이었다(10.1~27.9초). FE-GATE-013의 시스템 컨테이너는 같은
설치를 한 번 더 한다. merge 25분 목표에 0.8분 모자랐다.

고친 것(권하는 안으로 정함 2026-11-13, 총괄):
- job 단계 `dependency-cache`를 더한다. setup-node 앞에서 Node toolcache와
  `/tmp/fe-dependency-cache`(corepack, pnpm store, pnpm 메타데이터 캐시)를
  `.nvmrc`·`pnpm-lock.yaml` 해시 키로 복원한다. main run은 actions/cache로
  복원·저장하고, 그 밖의 ref는 actions/cache/restore로 복원만 한다. pin은
  짝 백엔드의 JDK·Gradle·Trivy 캐시와 같다(v4.3.0).
- 생성기가 그 job에 `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·
  `PNPM_CONFIG_CACHE_DIR`를 주어 job의 모든 pnpm 호출이 같은 곳을 본다.
  frozen install 단계는 그대로이고 캐시와 관계없이 돈다.
- PR run은 main이 저장한 항목을 같은 키로 읽기만 한다. 저장할 수 있는
  actions/cache 단계는 `refs/heads/main` 조건 아래에만 있고, 그 밖의 ref가
  타는 actions/cache/restore에는 저장하는 post 단계가 없다(시험으로 고정).
- 계약: merge job 셋만 이 단계를 가진다(release·promotion·provider·main
  job은 거절, 단계 순서 고정에 반영). 그 env를 job이 따로 묶으면 거절한다.
  키 입력은 `config/repository-layout.json`의 새 집합
  `dependency-cache-key`(`.nvmrc`, `pnpm-lock.yaml`)에서 고른다.
- `scripts/run-in-system-container.sh`가 그 env가 있으면 store와 메타데이터
  캐시를 같은 경로로 컨테이너에 넘긴다. 없으면(desktop) 지금과 같다.
- 결정 색인, ci-quality-gates.md, O1 출처 문구를 총괄이 정한 말로 맞춘다.

버린 대안:
- CI 이미지에 의존성 굽기: 레지스트리 쓰기 토큰이 든다.
- 브랜치 run도 저장하기: 캐시 항목은 다음 run이 믿는 입력이다. pnpm은
  같은 lockfile의 공급망 검증 기록이 캐시에 있으면 다시 검증하지 않으므로,
  브랜치가 쓴 항목이 main의 검증을 건너뛰게 할 수 있다.
- `cache-hit`일 때 설치를 건너뛰기: 결과가 캐시 상태에 달린다.
- apt 글꼴 캐시: 캐시가 없을 때 새 패키지 버전이 깔려 시각 결과가 달라질
  수 있다.

위험·한계:
- PR run은 main이 같은 키(또는 restore-keys로 앞 항목)를 저장한 뒤에야
  hit한다. 이 PR 자신의 run은 비어서 시작한다.
- runner 캐시 저장소(5GB)는 짝 백엔드와 같이 쓴다. 항목 하나는 Node·store·
  메타데이터로 압축 전 약 0.7GB다. lockfile이 바뀔 때마다 새 항목이 생긴다.
- Node toolcache 경로(`/opt/hostedtoolcache`)가 job 이미지와 다르면 그
  부분만 효과가 없고 setup-node가 내려받는다.

검증(desktop):
- 설치 실험(같은 lockfile, 새 폴더): 빈 캐시 13.9·17.2초, 캐시 있음 1.6초,
  store 파일 40개·메타데이터 40개를 망가뜨린 캐시 3.6초(27개만 다시 받음).
  다섯 번 모두 node_modules 트리 해시가 같다. pnpm 11은 대문자
  `PNPM_CONFIG_STORE_DIR`·`PNPM_CONFIG_CACHE_DIR`를 읽는다.
- FE-GATE-013 흐름을 캐시 env로 재현: 빈 캐시 설치 13.7초, 캐시 설치
  2.6초, 시스템 컨테이너 안 설치 1.5초(`Recreating node_modules` 없음, 지금은
  31.3초). 그 실행의 FE-GATE-013은 provider 묶음 시험 하나가 손 timeout
  30초에 걸려 실패했다(캐시와 무관, PR #39가 고치는 문제).
- RED: 계약·생성기를 둔 채 gates.json에서 캐시 단계를 빼면 새 시험 6개
  실패. 키 입력을 코드에 직접 적은 첫 판은 repository-layout R2 시험이
  잡았다. GREEN: repository-layout·ci-workflow-generation 456개 통과,
  check:ci·check:types·eslint rc=0, verify:documentation rc=0, 노트북
  `scripts/verify.sh docs` OK.
2026-11-13 08:26:13 +09:00

411 lines
16 KiB
JSON

{
"schemaVersion": 1,
"kinds": {
"source": "코드와 시험. 계층과 도구가 읽는다",
"tool-convention": "도구가 루트에서 이 이름으로 찾는 설정 파일·폴더",
"gate-input": "게이트와 런타임이 읽는 기준 데이터",
"document": "사람이 읽는 문서",
"history": "끝난 라운드의 기록. 이력 폴더로 옮길 대상이다(R10)",
"output": "실행 출력. 추적하는 것은 `.gitkeep`뿐이다(R3)",
"untracked": "추적하지 않는 로컬 항목(의존성·VCS·생성물·실행 출력·다른 worktree). 집합이 이름으로 고를 때만 적는다. 추적 파일이 없어야 한다"
},
"sets": {
"fixture-copy": "제거·생성 drill과 사본 시험이 복사하는 것(scripts/lib/removal-fixture.ts)",
"fixture-documents": "기능을 더하거나 지우는 drill이 문서까지 맞는지 보려고 더 복사하는 문서(scripts/lib/removal-fixture.ts)",
"secret-scan": "비밀값 검사가 꼭 있어야 한다고 보는 루트. config/security/secret-scan-policy.json의 trackedRoots가 이 집합과 같아야 한다. 검사와 공급망 목록 자체는 추적되는 파일 전부와 dist, artifacts/release를 본다(scripts/lib/repository-file-inventory.ts)",
"history-free": "이력 문서를 읽으면 안 되는 코드(tests/unit/deletable-history-documents.test.ts)",
"scale-source": "규모 증거에서 '지금 코드'를 정하는 입력(scripts/verify-extreme-scale.ts)",
"vite-build": "vite build가 읽는 입력(scripts/lib/vite-build-inputs.ts)",
"typescript-only": "JS 파일을 두면 안 되는 곳(scripts/check-architecture.ts)",
"checkout-copy-skip": "저장소 전체를 임시 폴더로 복사하는 시험이 건너뛰는 항목(tests/e2e/support/fixture-builds.ts, tests/e2e/support/service-worker-builds.ts, tests/unit/run-output-root-build.test.ts)",
"provider-fixture-skip": "provider 업로드 시험의 기준 fixture가 복사하지 않는 항목과 경로. .claude는 다른 worktree만 건너뛴다(tests/system/ci-runner/ci-artifact-contract.test.ts)",
"supply-chain-fixture-skip": "공급망 provider fixture가 복사하지 않는 항목. artifacts는 따로 복사한다(scripts/check-supply-chain-provider-fixtures.ts, tests/integration/security-followup-archive.test.ts)",
"fixture-code": "사본을 만들고 node_modules를 잇는 코드가 있는 곳. linkFixtureNodeModules 규칙을 보는 범위(scripts/check-adapter-inventory.ts, tests/unit/fixture-node-modules.test.ts)",
"package-manifest": "pnpm 설치를 정하는 매니페스트(tests/unit/fixture-node-modules.test.ts)",
"playwright-configs": "자기 forbidOnly를 가져야 하는 Playwright 설정. dev 설정은 기본 설정을 펼친다(scripts/check-test-evidence.ts)",
"visual-evidence": "시험 증거 검사가 있어야 한다고 보는 visual·workshop 입력(scripts/check-test-evidence.ts)",
"documentation-inputs": "verify:documentation이 읽는 문서 입력. 문서 시험이 사본으로 복사한다(tests/unit/documentation-readiness.test.ts, tests/unit/template-feature-removal-documents.test.ts)",
"agent-harness": "에이전트 하네스 파일(tests/unit/template-contract-documents.test.ts)",
"feature-typecheck": "기능 코드와 기능 시험을 타입 검사하는 tsconfig(tests/unit/manual-code-blocks.test.ts)",
"product-typecheck": "제품 사본을 타입 검사하는 tsconfig(tests/unit/product-extension-typecheck.test.ts)",
"app-typecheck": "앱 프로그램 tsconfig와 그 기반 설정(tests/unit/two-feature-install-typecheck.test.ts)",
"dependency-cache-key": "merge job 의존성 캐시의 키를 정하는 입력(scripts/contracts/ci-gates.ts의 DEPENDENCY_CACHE)"
},
"entries": [
{
"path": ".claude",
"kind": "tool-convention",
"role": "Claude Code 설정·규칙·스킬·서브에이전트",
"readBy": "Claude Code",
"sets": ["checkout-copy-skip", "agent-harness"],
"setPaths": {
"provider-fixture-skip": [".claude/worktrees"]
}
},
{
"path": ".dependency-cruiser.json",
"kind": "tool-convention",
"role": "import 규칙과 kernel 예외의 정본",
"readBy": "scripts/check-architecture.ts (FE-GATE-010)",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
},
{
"path": ".env.example",
"kind": "tool-convention",
"role": "빌드 시점 공개 변수의 견본",
"readBy": "Vite(VITE_*), 사람"
},
{
"path": ".generated",
"kind": "untracked",
"role": "빌드가 쓰는 런타임 생성물(.generated/frontend-runtime)",
"readBy": "scripts/build-frontend.ts, scripts/generate-contract-set.ts",
"optional": true,
"sets": ["checkout-copy-skip"]
},
{
"path": ".git",
"kind": "untracked",
"role": "git 저장소. worktree에서는 파일이다",
"readBy": "git",
"optional": true,
"sets": ["checkout-copy-skip"]
},
{
"path": ".gitattributes",
"kind": "tool-convention",
"role": "git 병합 규칙(작업 장부 docs/ledger/estimates.jsonl을 union으로 합친다)",
"readBy": "git"
},
{
"path": ".gitea",
"kind": "tool-convention",
"role": "Gitea Actions workflow. config/ci/gates.json에서 생성한다",
"readBy": "Gitea Actions, scripts/generate-ci-workflow.ts, check:ci (FE-GATE-010)",
"sets": ["fixture-copy", "history-free"],
"setPaths": {
"secret-scan": [".gitea/workflows/quality-gates.yml"]
}
},
{
"path": ".gitignore",
"kind": "tool-convention",
"role": "추적하지 않을 파일",
"readBy": "git",
"sets": ["fixture-copy"]
},
{
"path": ".npmrc",
"kind": "tool-convention",
"role": "pnpm 설정",
"readBy": "pnpm",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": ".nvmrc",
"kind": "tool-convention",
"role": "Node 버전",
"readBy": "nvm, CI",
"sets": ["fixture-copy", "secret-scan", "dependency-cache-key"]
},
{
"path": ".release",
"kind": "untracked",
"role": "CI가 만드는 릴리스 후보 묶음",
"readBy": "release 단계 job(config/ci/gates.json)",
"optional": true,
"sets": ["provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": ".storybook",
"kind": "tool-convention",
"role": "Storybook 설정. 갤러리와 visual 골든의 대상",
"readBy": "storybook, build:storybook (FE-GATE-011)",
"sets": ["fixture-copy", "secret-scan", "scale-source", "typescript-only"]
},
{
"path": ".tmp",
"kind": "untracked",
"role": "drill 사본과 실행별 빌드·결과(.tmp/runs/<id>)",
"readBy": "scripts/lib/run-isolation.ts, 제거 drill",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip"]
},
{
"path": ".worktrees",
"kind": "untracked",
"role": "이 저장소의 다른 worktree를 두는 자리",
"readBy": "git worktree",
"optional": true,
"sets": ["provider-fixture-skip"]
},
{
"path": "AGENTS.md",
"kind": "tool-convention",
"role": "에이전트 진입 문서(꼭 지킬 것·지도·검증). docs/README.md 1절이 가리키는 현재 계약 문서",
"readBy": "코딩 에이전트, verify:documentation (FE-GATE-017)",
"sets": ["fixture-documents", "agent-harness"]
},
{
"path": "CHANGELOG.md",
"kind": "document",
"role": "버전별 변경과 다운스트림이 할 일",
"readBy": "tests/unit/changelog-review-ids.test.ts, 사람",
"sets": ["fixture-documents"]
},
{
"path": "CLAUDE.md",
"kind": "tool-convention",
"role": "Claude Code 진입 문서",
"readBy": "Claude Code",
"sets": ["agent-harness"]
},
{
"path": "PRODUCT.md",
"kind": "tool-convention",
"role": "제품 맥락. 디자인 도구가 루트에서 찾는다",
"readBy": "디자인 스킬"
},
{
"path": "README.md",
"kind": "document",
"role": "시작·설정·검증",
"readBy": "verify:documentation (FE-GATE-017), 사람",
"sets": ["fixture-documents", "documentation-inputs"]
},
{
"path": "artifacts",
"kind": "output",
"role": "게이트와 시험의 실행 출력",
"readBy": "scripts/run-ci-gate.ts, CI 업로드",
"sets": ["checkout-copy-skip", "provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": "config",
"kind": "gate-input",
"role": "게이트·런타임·보안·성능의 기준 데이터와 JSON Schema(config/schemas)",
"readBy": "scripts/, tests/, src/",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"],
"setPaths": {
"documentation-inputs": ["config/contracts/backend-contract-pin.json"]
}
},
{
"path": "dist",
"kind": "untracked",
"role": "vite build 출력",
"readBy": "vite build, preview 서버",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": "docs",
"kind": "document",
"role": "매뉴얼·설계·운영 문서와 수동 접근성 검토 기록",
"readBy": "verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009·028)",
"sets": ["fixture-documents", "documentation-inputs"],
"setPaths": {
"fixture-copy": ["docs/accessibility/route-reviews"],
"agent-harness": ["docs/work"]
}
},
{
"path": "eslint.config.ts",
"kind": "tool-convention",
"role": "lint 규칙",
"readBy": "eslint (FE-GATE-002)",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
},
{
"path": "graphify-out",
"kind": "untracked",
"role": "graphify 지식 그래프 출력(로컬 분석)",
"readBy": "graphify",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip"]
},
{
"path": "index.html",
"kind": "tool-convention",
"role": "Vite 진입 HTML",
"readBy": "Vite",
"sets": ["fixture-copy", "secret-scan", "vite-build"]
},
{
"path": "node_modules",
"kind": "untracked",
"role": "설치된 의존성",
"readBy": "pnpm, Node",
"optional": true,
"sets": ["checkout-copy-skip", "provider-fixture-skip", "supply-chain-fixture-skip"]
},
{
"path": "package.json",
"kind": "tool-convention",
"role": "의존성과 package script",
"readBy": "pnpm, 모든 게이트",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build", "package-manifest"]
},
{
"path": "playwright.capabilities.config.ts",
"kind": "tool-convention",
"role": "브라우저 capability 시험 설정",
"readBy": "test:browser-capabilities (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan", "playwright-configs"]
},
{
"path": "playwright.config.ts",
"kind": "tool-convention",
"role": "e2e 설정(빌드 미리보기)",
"readBy": "test:e2e (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan", "history-free", "playwright-configs"]
},
{
"path": "playwright.dev.config.ts",
"kind": "tool-convention",
"role": "dev 서버 대상 e2e 설정",
"readBy": "test:e2e:dev",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "playwright.storybook.config.ts",
"kind": "tool-convention",
"role": "Storybook 정적 빌드 시험 설정",
"readBy": "test:storybook (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan", "playwright-configs", "visual-evidence"]
},
{
"path": "playwright.visual.config.ts",
"kind": "tool-convention",
"role": "visual 골든 설정",
"readBy": "test:visual (FE-GATE-008)",
"sets": ["fixture-copy", "secret-scan", "playwright-configs", "visual-evidence"]
},
{
"path": "pnpm-lock.yaml",
"kind": "tool-convention",
"role": "잠금 파일",
"readBy": "pnpm, 공급망 생성",
"sets": ["fixture-copy", "secret-scan", "scale-source", "package-manifest", "dependency-cache-key"]
},
{
"path": "pnpm-workspace.yaml",
"kind": "tool-convention",
"role": "pnpm 11 설정",
"readBy": "pnpm, scripts/lib/package-script-graph.ts",
"sets": ["fixture-copy", "secret-scan", "package-manifest"]
},
{
"path": "public",
"kind": "tool-convention",
"role": "개발 서버가 서빙하는 런타임 문서",
"readBy": "Vite",
"sets": ["fixture-copy", "secret-scan", "vite-build"]
},
{
"path": "recipes",
"kind": "source",
"role": "선택 기능 설치 원본. 기본 빌드에 들어가지 않는다",
"readBy": "tsconfig.test.json, test:recipes (FE-GATE-007), check:optional-recipes (FE-GATE-012)",
"optional": true,
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only"]
},
{
"path": "renovate.json",
"kind": "tool-convention",
"role": "보안 업데이트 봇 설정",
"readBy": "Renovate"
},
{
"path": "scripts",
"kind": "source",
"role": "게이트·생성기·drill 스크립트",
"readBy": "package.json scripts",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only", "fixture-code"],
"setPaths": {
"vite-build": ["scripts/lib/run-isolation.ts", "scripts/lib/vite-module-inventory.ts"]
}
},
{
"path": "src",
"kind": "source",
"role": "앱 계층",
"readBy": "빌드와 모든 게이트",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build", "typescript-only"]
},
{
"path": "tests",
"kind": "source",
"role": "시험과 fixture",
"readBy": "test:* scripts, playwright 설정",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "typescript-only", "fixture-code"],
"setPaths": {
"visual-evidence": ["tests/storybook/workshop.spec.ts"]
}
},
{
"path": "tsconfig.app.json",
"kind": "tool-convention",
"role": "src 타입 검사(DOM, Node 타입 없음)",
"readBy": "check:types:app (FE-GATE-003), Vite",
"sets": ["fixture-copy", "secret-scan", "scale-source", "vite-build", "feature-typecheck", "product-typecheck", "app-typecheck"]
},
{
"path": "tsconfig.base.json",
"kind": "tool-convention",
"role": "공통 컴파일 옵션",
"readBy": "다른 tsconfig의 extends",
"sets": ["fixture-copy", "secret-scan", "vite-build", "app-typecheck"]
},
{
"path": "tsconfig.json",
"kind": "tool-convention",
"role": "편집기용 solution tsconfig(files 없음, references만)",
"readBy": "편집기",
"sets": ["fixture-copy", "secret-scan", "scale-source"]
},
{
"path": "tsconfig.node.json",
"kind": "tool-convention",
"role": "scripts·설정 파일 타입 검사(NodeNext)",
"readBy": "check:types:node (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan", "scale-source", "product-typecheck"]
},
{
"path": "tsconfig.service-worker.json",
"kind": "tool-convention",
"role": "Service Worker 타입 검사(WebWorker, DOM 없음)",
"readBy": "check:types:service-worker (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "tsconfig.test.json",
"kind": "tool-convention",
"role": "tests·recipes·시험 설정 파일 타입 검사",
"readBy": "check:types:test (FE-GATE-003)",
"sets": ["fixture-copy", "secret-scan", "scale-source", "feature-typecheck", "product-typecheck"]
},
{
"path": "vite.config.ts",
"kind": "tool-convention",
"role": "앱 빌드",
"readBy": "Vite",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source", "vite-build"]
},
{
"path": "vite.service-worker.config.ts",
"kind": "tool-convention",
"role": "Service Worker 빌드",
"readBy": "scripts/build-frontend.ts",
"sets": ["fixture-copy", "secret-scan"]
},
{
"path": "vitest.config.ts",
"kind": "tool-convention",
"role": "단위·컴포넌트 시험 설정",
"readBy": "scripts/run-vitest.ts",
"sets": ["fixture-copy", "secret-scan", "history-free", "scale-source"]
}
]
}