문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N" 처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4). 가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에 있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지 못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다: docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로, docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와 docs/superpowers/plans의 계획으로. 고른 방법: - 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞 커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절 번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다. - tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 + "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에 .dependency-cruiser.json을 넣는다. - README "Files you can delete after copying"에서 INVENTORY.md 한 파일 대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과 ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다. INVENTORY의 행 구조는 바꾸지 않는다. - 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은 링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다. 버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도 상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기 목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시 다른 이력을 가리키면 남길 목록이 계속 커진다. 위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는 주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다. src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼 이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미 docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의 이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다. check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던 실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가 바뀐다. 검증: - RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed). - GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를 src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림. - 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0). - 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크 148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계 참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서 verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트 2 passed. - node scripts/verify-documentation-readiness.ts: PASS_SCOPED - node scripts/check-adapter-inventory.ts: PASS - node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts: 50 passed. tests/architecture: 39 passed. - npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과. .dependency-cruiser.json JSON 파싱 통과. - 미실행: check:architecture(pnpm 필요).
360 lines
18 KiB
JSON
360 lines
18 KiB
JSON
{
|
|
"forbidden": [
|
|
{
|
|
"name": "domain-is-framework-neutral",
|
|
"comment": "domain holds framework-neutral models and pure policies. Keep the dependency out: move the code to application, or pass the value in from there.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/domain"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(application|presentation|adapters|bootstrap)|react|react-dom|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "application-does-not-know-concrete-runtime",
|
|
"comment": "application owns use cases and the ports they need. Declare a port under src/application/ports and let src/bootstrap pass the concrete adapter.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/application"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(presentation|adapters|bootstrap)|react|react-dom|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "presentation-does-not-know-adapters",
|
|
"comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/presentation/(?!adapters/query)"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(adapters|bootstrap)|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "page-templates-own-layout-only",
|
|
"comment": "Page templates own layout only. Take data and actions as props from the page that uses the template.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/presentation/templates"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(application|adapters|bootstrap)|src/presentation/adapters|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "icon-vendor-is-facade-only",
|
|
"comment": "VD-05. lucide-react is imported by the icon vendor facade only; product code uses the semantic icons from the design-system index, so replacing the vendor touches one file.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src",
|
|
"pathNot": "^src/presentation/design-system/icons/vendors/lucide\\.tsx$"
|
|
},
|
|
"to": {
|
|
"path": "^lucide-react$"
|
|
}
|
|
},
|
|
{
|
|
"name": "zod-is-reached-through-contracts-zod",
|
|
"comment": "F-7 (13-08). src/contracts/zod.ts sets zod jitless before any schema is built, so the production CSP never sees zod's Function probe. Schema code imports z from there.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src",
|
|
"pathNot": "^src/contracts/zod\\.ts$"
|
|
},
|
|
"to": {
|
|
"path": "^zod$"
|
|
}
|
|
},
|
|
{
|
|
"name": "design-system-is-reached-through-its-index",
|
|
"comment": "VD-05, 12-08. Code outside src/presentation/design-system imports its public index.ts only, so the primitives can change behind it. Named facades: src/presentation/components/ui/*.ts re-export the canonical primitives under their pre-VD-05 paths (VD-05 Rollback). Exception: src/presentation/templates/page-templates.tsx reads PaginationLandmarkContext, which index.ts does not export. Owner: frontend-platform. Revisit: export it from index.ts or move the page templates into the design system.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/",
|
|
"pathNot": "^src/presentation/(design-system/|components/ui/[^/]+\\.ts$|templates/page-templates\\.tsx$)"
|
|
},
|
|
"to": {
|
|
"path": "^src/presentation/design-system/",
|
|
"pathNot": "^src/presentation/design-system/index\\.ts$"
|
|
}
|
|
},
|
|
{
|
|
"name": "adapters-do-not-know-presentation",
|
|
"comment": "An adapter implements an application port. It never imports UI or the composition root; pass what it needs through the port or its factory arguments.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/adapters"
|
|
},
|
|
"to": {
|
|
"path": "^src/(presentation|bootstrap)"
|
|
}
|
|
},
|
|
{
|
|
"name": "feature-domain-is-framework-neutral",
|
|
"comment": "A feature's domain is framework-neutral, like src/domain. Move the code to the feature's application, or pass the value in from there.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/features/[^/]+/domain"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(application|presentation|adapters|bootstrap)|src/features/[^/]+/(application|adapters|presentation)|react|react-dom|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "feature-application-does-not-know-runtime",
|
|
"comment": "A feature's application declares the ports it needs. Put the port in the feature's application and implement it in the feature's adapters/; bootstrap wires the two.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/features/[^/]+/application"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(presentation|adapters|bootstrap)|src/features/[^/]+/(adapters|presentation)|react|react-dom|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "feature-presentation-does-not-know-outbound-adapters",
|
|
"comment": "Feature presentation calls its application API. The feature's adapters/ are wired by bootstrap, so import the application facade instead.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/features/[^/]+/presentation"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(adapters|bootstrap)|src/features/[^/]+/adapters|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "feature-adapters-do-not-know-presentation",
|
|
"comment": "A feature adapter implements the feature's ports and never imports UI or the composition root. Pass what it needs through the port.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/features/[^/]+/adapters"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(presentation|bootstrap)|src/features/[^/]+/presentation)"
|
|
}
|
|
},
|
|
{
|
|
"name": "concrete-adapters-compose-only-in-bootstrap",
|
|
"comment": "Only src/bootstrap constructs concrete adapters. Depend on the application port or facade; bootstrap composes the adapter behind it.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/(domain|application|presentation|contracts)"
|
|
},
|
|
"to": {
|
|
"path": "^src/adapters"
|
|
}
|
|
},
|
|
{
|
|
"name": "external-contract-package-single-import-path",
|
|
"comment": "§4.1: a generated service package may only be imported from src/features/<feature>/contracts/*-contract-contribution.ts. Owner: frontend-platform.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src",
|
|
"pathNot": "^src/features/[^/]+/contracts/[^/]+-contract-contribution\\.ts$"
|
|
},
|
|
"to": {
|
|
"path": "^@org-contracts/"
|
|
}
|
|
},
|
|
{
|
|
"name": "presentation-does-not-fetch-directly",
|
|
"comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself. Call the application API; bootstrap composes the adapter behind it.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/(presentation|features/[^/]+/presentation)"
|
|
},
|
|
"to": {
|
|
"path": "^src/adapters/(http|realtime|service-worker|web-worker|storage)"
|
|
}
|
|
},
|
|
{
|
|
"name": "unselected-realtime-runtime-is-not-composed",
|
|
"comment": "§9.2 / 12-10. Realtime and Web Push are NOT_SELECTED in the template (src/features/installed-runtime-capabilities.ts), so the composition root and the installed-feature registries do not import their concrete adapters. A project that selects one replaces this rule when it wires the runtime. Owner: frontend-platform.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/(bootstrap/|features/installed-feature-)"
|
|
},
|
|
"to": {
|
|
"path": "^src/adapters/(realtime|web-push)/"
|
|
}
|
|
},
|
|
{
|
|
"name": "generic-worker-has-no-network-or-credentials",
|
|
"comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth. Do the network call on the page side and post the data to the worker.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/adapters/web-worker"
|
|
},
|
|
"to": {
|
|
"path": "^src/adapters/(http|realtime|auth|web-push)"
|
|
}
|
|
},
|
|
{
|
|
"name": "service-worker-entry-is-not-page-code",
|
|
"comment": "§17.2.1: the worker realm never imports React, presentation or bootstrap page code",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/adapters/service-worker"
|
|
},
|
|
"to": {
|
|
"path": "^(src/(presentation|bootstrap)|react|react-dom|@tanstack)"
|
|
}
|
|
},
|
|
{
|
|
"name": "contracts-do-not-know-application",
|
|
"comment": "§4. `src/contracts` is the lower of the two packages: application reads contracts, never the other way round. Before this rule the shared Result carrier and the compatibility predicate lived in application and were imported back down by contracts, so neither package owned the shared vocabulary and the coupling was invisible to every gate.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/contracts"
|
|
},
|
|
"to": {
|
|
"path": "^src/(application|features)"
|
|
}
|
|
},
|
|
{
|
|
"name": "contracts-do-not-know-presentation-or-bootstrap",
|
|
"comment": "Q-6.7-12. `src/contracts` is shared vocabulary read by every layer, including the service worker and web worker builds. Importing presentation or the composition root from it would pull React and the whole app into those builds. There is no such import today; this keeps it that way.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/contracts"
|
|
},
|
|
"to": {
|
|
"path": "^src/(presentation|bootstrap)"
|
|
}
|
|
},
|
|
{
|
|
"name": "generic-presentation-does-not-compose-the-product",
|
|
"comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Exception: the generic presentation modules in pathNot read the installed registries today. The list names exact files, so a new module that reads a registry fails the gate. Owner: frontend-platform. Revisit when the assembly is lifted into bootstrap; remove each file from the list as it stops reading the registries.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/presentation/",
|
|
"pathNot": "^src/presentation/(layouts/app-shell\\.tsx|pages/(not-found-page|home-page)\\.tsx|routes/(route-contract|route-codecs|app-router|navigation-policy)\\.(ts|tsx)|i18n/catalog\\.ts|examples/platform-overview-page\\.tsx)$"
|
|
},
|
|
"to": {
|
|
"path": "^src/features/installed-"
|
|
}
|
|
},
|
|
{
|
|
"name": "boot-does-not-load-every-feature-runtime",
|
|
"comment": "15-01. src/features/loaded-feature-runtimes.ts awaits every installed feature's runtime half at module evaluation. Imported anywhere on the boot path, the first render would wait for all feature code, and the initial-chunk budget would not see it because the runtimes are dynamic imports. Any top-level await in the browser graph also turns off rolldown chunk optimizations for the whole build. At runtime the composition root loads one feature at a time when its routes are entered; the platform overview route calls loadInstalledFeatureRuntimeRegistries() instead. Node scripts and tests are outside src and may import it. Owner: frontend-platform.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/",
|
|
"pathNot": "^src/features/loaded-feature-runtimes\\.ts$"
|
|
},
|
|
"to": {
|
|
"path": "^src/features/loaded-feature-runtimes\\.ts$"
|
|
}
|
|
},
|
|
{
|
|
"name": "adapters-do-not-know-other-concrete-adapters",
|
|
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (clock, abort primitive, capacity guard), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/adapters/([^/]+)/"
|
|
},
|
|
"to": {
|
|
"path": "^src/adapters/([^/]+)/",
|
|
"pathNot": "^src/adapters/($1/|platform/|browser-file-storage/result\\.ts$|cross-context-invalidation/index\\.ts$)"
|
|
}
|
|
},
|
|
{
|
|
"name": "adapter-groups-are-reached-through-their-barrel",
|
|
"comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 예외: 도착점에서 storage/indexeddb/index.ts와 storage/opfs/index.ts만 서브배럴로 허용한다. 두 폴더는 browser-file-storage 번들의 런타임이고, 제거 드릴(scripts/test-browser-file-storage-runtime-removal.ts)은 그 번들 전체(browser-file-storage, browser-files, browser-transfer, cache-storage, storage/indexeddb, storage/opfs)를 함께 지운다. 최상위 storage 배럴(Web Storage)은 그 뒤에도 남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개 경계다. 다른 2단계 index.ts는 공개 배럴이 아니다(리뷰 12-07). 담당: frontend-platform. 재검토: 새 런타임을 따로 제거할 수 있게 만들 때 그 서브배럴을 이 목록에 추가한다.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/",
|
|
"pathNot": "^src/adapters/"
|
|
},
|
|
"to": {
|
|
"path": "^src/adapters/[^/]+/",
|
|
"pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/storage/(indexeddb|opfs)/index\\.ts$"
|
|
}
|
|
},
|
|
{
|
|
"name": "features-do-not-import-other-features",
|
|
"comment": "A feature may depend on shared contracts/ports, but never on another feature concrete implementation.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/features/([^/]+)/"
|
|
},
|
|
"to": {
|
|
"path": "^src/features/[^/]+/",
|
|
"pathNot": "^src/features/$1/"
|
|
}
|
|
},
|
|
{
|
|
"name": "contexts-do-not-import-other-contexts",
|
|
"comment": "A bounded context may compose its own features and shared platform contracts, but not another context concrete implementation.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/contexts/([^/]+)/"
|
|
},
|
|
"to": {
|
|
"path": "^src/contexts/[^/]+/",
|
|
"pathNot": "^src/contexts/$1/"
|
|
}
|
|
},
|
|
{
|
|
"name": "feature-and-app-roots-do-not-reach-adapters",
|
|
"comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers the files outside a feature's layer folders (src/features/*.ts, src/features/<feature>/*.ts), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/(features/[^/]+\\.tsx?$|features/[^/]+/[^/]+\\.tsx?$|contexts/|apps/)",
|
|
"pathNot": "^src/features/feature-adapter-contribution\\.ts$"
|
|
},
|
|
"to": {
|
|
"path": "^src/adapters/"
|
|
}
|
|
},
|
|
{
|
|
"name": "presentation-does-not-import-apps-or-contexts",
|
|
"comment": "12-03. Apps and contexts compose features, including their runtime, so presentation importing them is a path around presentation-does-not-know-adapters. Exception: src/presentation/routes/app-router.tsx mounts the deployable app's route tree (src/apps/template-app.ts). Owner: frontend-platform. Revisit when the router is assembled in bootstrap together with the frozen generic-presentation-does-not-compose-the-product list.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/(presentation/|features/[^/]+/presentation/)",
|
|
"pathNot": "^src/presentation/routes/app-router\\.tsx$"
|
|
},
|
|
"to": {
|
|
"path": "^src/(apps|contexts)/"
|
|
}
|
|
},
|
|
{
|
|
"name": "observability-vendors-live-behind-adapters",
|
|
"comment": "scale-architecture.md §24. Features, platform, application, domain, contracts and presentation emit observability only through the provider-neutral TelemetryPort. A vendor telemetry SDK may be imported only by an adapter-side transport under src/adapters.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/",
|
|
"pathNot": "^src/adapters/"
|
|
},
|
|
"to": {
|
|
"path": "^(@sentry|@datadog|@opentelemetry|@newrelic|newrelic|@honeycombio|@bugsnag|bugsnag-js|@rollbar|rollbar|logrocket|@logrocket|@amplitude|posthog-js|mixpanel-browser|@segment|@elastic/apm-rum|@grafana/faro-web-sdk|@microsoft/applicationinsights-web)(/|$)"
|
|
}
|
|
},
|
|
{
|
|
"name": "platform-kernel-is-product-neutral",
|
|
"comment": "scale-architecture.md §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.",
|
|
"severity": "error",
|
|
"from": {
|
|
"path": "^src/platform/",
|
|
"pathNot": "^src/platform/routing/"
|
|
},
|
|
"to": {
|
|
"path": "^src/(features|contexts|apps|adapters|bootstrap|presentation|application)/"
|
|
}
|
|
},
|
|
{
|
|
"name": "no-circular-dependencies",
|
|
"comment": "A cycle makes the modules impossible to load or remove one at a time. Move the shared part into a lower module that both import.",
|
|
"severity": "error",
|
|
"from": {},
|
|
"to": {
|
|
"circular": true
|
|
}
|
|
}
|
|
]
|
|
}
|