fix(docs): 입구 문서를 실제 src 폴더 9개와 규칙 이름에 맞추고 검사한다 (14-03)
문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
(failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
This commit is contained in:
@@ -137,15 +137,32 @@ This repository is a **Frontend Application Foundation**: a starter/composition
|
||||
skeleton plus a reusable capability platform. Platform capabilities stay
|
||||
horizontal while product business features use vertical slices.
|
||||
|
||||
Dependencies point inward:
|
||||
`src/` has nine top-level folders. The descriptions match the table in
|
||||
`docs/architecture/layers.md`, which also names every import rule:
|
||||
|
||||
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
|
||||
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
|
||||
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
|
||||
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
|
||||
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
|
||||
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
|
||||
- `src/application` — generic use cases, ports, policies and view-models
|
||||
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
|
||||
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
|
||||
|
||||
Dependencies point inward. Every folder may also import `contracts` and
|
||||
`platform`:
|
||||
|
||||
```text
|
||||
presentation -> application -> domain
|
||||
presentation -> application -> contracts -> platform
|
||||
adapters -----^
|
||||
bootstrap composes concrete adapters
|
||||
apps -> contexts -> features (an app deploys contexts; a context owns features)
|
||||
feature use case -> feature port <- feature-owned capability binding
|
||||
```
|
||||
|
||||
Domain code lives inside each feature; there is no top-level domain folder.
|
||||
|
||||
See
|
||||
`docs/architecture/frontend-application-foundation.md`,
|
||||
`docs/architecture/overview.md`, `docs/architecture/layers.md`, and
|
||||
|
||||
@@ -19,6 +19,9 @@ The placement rule is:
|
||||
- one feature owner -> keep it under that feature,
|
||||
- one reusable capability owner -> keep it under that adapter/capability and
|
||||
export it through the capability public entry point,
|
||||
- a product-neutral primitive any layer may call, with no product vocabulary
|
||||
in it (a budget, deadline, retry, execution context, telemetry pipeline step
|
||||
or error envelope) -> `src/platform`,
|
||||
- multiple independent capability/layer owners -> `src/contracts`,
|
||||
- browser/build/release wire or artifact authority -> `src/contracts` even
|
||||
when the browser source graph alone looks small.
|
||||
@@ -26,6 +29,17 @@ The placement rule is:
|
||||
Consumer count alone is not sufficient. Scripts, generated artifacts and
|
||||
release gates are semantic consumers too.
|
||||
|
||||
`src/platform` and `src/contracts` differ in what they hold. `src/contracts`
|
||||
holds the product's shared vocabulary: registries, schemas and wire formats
|
||||
such as routes, API operations, storage keys and release artifacts.
|
||||
`src/platform` holds mechanisms that work without that vocabulary, plus the
|
||||
few error kinds no feature owns (network, deadline, cancellation, response
|
||||
bounds). Today `src/contracts` imports `src/platform` and not the other way
|
||||
round. `platform-kernel-is-product-neutral` stops `src/platform` from importing
|
||||
any feature, context, app, adapter, bootstrap, presentation or application
|
||||
module. A primitive that needs a route, an API operation or a feature's
|
||||
vocabulary is not product-neutral: put it in `src/contracts` or with its owner.
|
||||
|
||||
## Audit result
|
||||
|
||||
The September 2026 architecture review triggered an import-graph audit of all
|
||||
|
||||
@@ -15,16 +15,29 @@ do not have to understand that internal sophistication.
|
||||
|
||||
## Hybrid architecture
|
||||
|
||||
`src/` has nine top-level folders. The descriptions match the table in
|
||||
[the layer contract](./layers.md), which also names every import rule.
|
||||
|
||||
Platform code is horizontal:
|
||||
|
||||
- `application`: generic application inputs/policies/ports
|
||||
- `contracts`: genuinely cross-capability shared vocabulary and registries
|
||||
- `adapters`: reusable capability runtimes
|
||||
- `presentation`: generic UI/routing/query integration
|
||||
- `bootstrap`: concrete composition
|
||||
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
|
||||
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
|
||||
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
|
||||
- `src/application` — generic use cases, ports, policies and view-models
|
||||
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
|
||||
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
|
||||
|
||||
Ownership declarations group features into deployable units:
|
||||
|
||||
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
|
||||
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
|
||||
|
||||
Product business code is vertical:
|
||||
|
||||
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
|
||||
|
||||
Inside one feature:
|
||||
|
||||
- `features/<feature>/domain`
|
||||
- `features/<feature>/application`
|
||||
- `features/<feature>/contracts`
|
||||
|
||||
+83
-36
@@ -1,44 +1,84 @@
|
||||
# Clean Architecture layer contract
|
||||
|
||||
The import direction is `domain <- application <- presentation`; concrete
|
||||
adapters implement application-owned ports and are assembled only in
|
||||
`src/bootstrap`.
|
||||
Dependencies point inward: `presentation -> application -> contracts ->
|
||||
platform`. Concrete adapters implement application-owned ports and are
|
||||
assembled only in `src/bootstrap`.
|
||||
|
||||
| Layer | Owns | May depend on |
|
||||
## Top-level folders
|
||||
|
||||
`src/` has these nine folders and no others:
|
||||
|
||||
| Folder | Owns |
|
||||
| --- | --- |
|
||||
| `src/bootstrap` | the composition root: runtime configuration, concrete adapter construction and the React mount |
|
||||
| `src/apps` | deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces |
|
||||
| `src/contexts` | bounded contexts: each `context-module.ts` declares its app, route root and feature budget |
|
||||
| `src/features` | removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`) |
|
||||
| `src/presentation` | generic UI and the inbound adapter: routes, layouts, the design system, pages and providers |
|
||||
| `src/adapters` | reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more |
|
||||
| `src/application` | generic use cases, ports, policies and view-models |
|
||||
| `src/contracts` | shared vocabulary and registries read by several layers, the workers and the build and release scripts |
|
||||
| `src/platform` | product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence |
|
||||
|
||||
Domain code lives inside a feature (`src/features/<id>/domain`). There is no
|
||||
top-level domain folder. If a project adds one, `domain-is-framework-neutral`
|
||||
and `concrete-adapters-compose-only-in-bootstrap` already cover it.
|
||||
|
||||
`src/adapters/platform` is the adapter kernel (below). It is not
|
||||
`src/platform`.
|
||||
|
||||
Where a shared type or primitive goes is decided in
|
||||
[contract ownership](./contract-ownership.md).
|
||||
|
||||
## Rules
|
||||
|
||||
Each row is one `forbidden` rule in `.dependency-cruiser.json`, by its `name`.
|
||||
"Forbids" lists what code under "Applies to" must not import.
|
||||
|
||||
| Rule | Applies to | Forbids |
|
||||
| --- | --- | --- |
|
||||
| `domain` | framework-neutral models and pure policies | domain siblings |
|
||||
| `application` | use cases, ports, orchestration, view-models | domain and application siblings |
|
||||
| `presentation` | routes, components, user interaction and view state | application public API and shared UI |
|
||||
| `adapters` | browser and third-party implementations of application ports | application ports and limited domain values |
|
||||
| `features/<id>` | removable vertical domain/application/contracts/adapters/presentation slice | the same inward rule plus platform public boundaries |
|
||||
| `bootstrap` | runtime configuration, adapter construction and React mount | all selected runtime modules |
|
||||
| `domain-is-framework-neutral` | a top-level domain folder (none today) | application, presentation, adapters, bootstrap, React, TanStack |
|
||||
| `application-does-not-know-concrete-runtime` | `src/application` | presentation, adapters, bootstrap, React, TanStack |
|
||||
| `presentation-does-not-know-adapters` | `src/presentation`, except `adapters/query` | adapters, bootstrap, TanStack |
|
||||
| `page-templates-own-layout-only` | `src/presentation/templates` | application, adapters, bootstrap, the presentation query adapter, TanStack. Templates take data and actions as props |
|
||||
| `icon-vendor-is-facade-only` | all of `src`, except the lucide vendor facade | `lucide-react` |
|
||||
| `zod-is-reached-through-contracts-zod` | all of `src`, except `src/contracts/zod.ts` | `zod` |
|
||||
| `design-system-is-reached-through-its-index` | code outside the design system and its named facades | design-system files other than its `index.ts` |
|
||||
| `adapters-do-not-know-presentation` | `src/adapters` | presentation, bootstrap |
|
||||
| `feature-domain-is-framework-neutral` | `src/features/<id>/domain` | application, presentation, adapters, bootstrap, any feature's application, adapters and presentation, React, TanStack |
|
||||
| `feature-application-does-not-know-runtime` | `src/features/<id>/application` | presentation, adapters, bootstrap, any feature's adapters and presentation, React, TanStack |
|
||||
| `feature-presentation-does-not-know-outbound-adapters` | `src/features/<id>/presentation` | adapters, bootstrap, any feature's adapters, TanStack |
|
||||
| `feature-adapters-do-not-know-presentation` | `src/features/<id>/adapters` | presentation, bootstrap, any feature's presentation |
|
||||
| `concrete-adapters-compose-only-in-bootstrap` | `src/application`, `src/presentation`, `src/contracts` | `src/adapters` |
|
||||
| `external-contract-package-single-import-path` | all of `src`, except `src/features/<id>/contracts/*-contract-contribution.ts` | the generated `@org-contracts/*` service packages |
|
||||
| `presentation-does-not-fetch-directly` | generic and feature presentation | the HTTP, realtime, service-worker, web-worker and storage adapters |
|
||||
| `unselected-realtime-runtime-is-not-composed` | `src/bootstrap`, `src/features/installed-feature-*` | the realtime and Web Push adapters, which the template does not select |
|
||||
| `generic-worker-has-no-network-or-credentials` | `src/adapters/web-worker` | the HTTP, realtime, auth and Web Push adapters |
|
||||
| `service-worker-entry-is-not-page-code` | `src/adapters/service-worker` | presentation, bootstrap, React, TanStack |
|
||||
| `contracts-do-not-know-application` | `src/contracts` | application, features. Contracts is the lower package and owns the vocabulary both read |
|
||||
| `contracts-do-not-know-presentation-or-bootstrap` | `src/contracts` | presentation, bootstrap |
|
||||
| `generic-presentation-does-not-compose-the-product` | `src/presentation`, except the files the rule lists | the installed-feature registries. Which features exist is a product decision owned by `src/bootstrap` |
|
||||
| `boot-does-not-load-every-feature-runtime` | all of `src`, except the module itself | `src/features/loaded-feature-runtimes.ts` |
|
||||
| `adapters-do-not-know-other-concrete-adapters` | each adapter group | another adapter group, except the adapter kernel |
|
||||
| `adapter-groups-are-reached-through-their-barrel` | code outside `src/adapters` | adapter files other than a group's `index.ts` and the `storage/indexeddb` and `storage/opfs` sub-barrels |
|
||||
| `features-do-not-import-other-features` | each feature | another feature |
|
||||
| `contexts-do-not-import-other-contexts` | each context | another context |
|
||||
| `feature-and-app-roots-do-not-reach-adapters` | `src/features/*.ts`, `src/features/<id>/*.ts`, `src/contexts`, `src/apps`, except the type-only `src/features/feature-adapter-contribution.ts` | `src/adapters` |
|
||||
| `presentation-does-not-import-apps-or-contexts` | generic and feature presentation, except `src/presentation/routes/app-router.tsx`, which mounts the app's route tree | `src/apps`, `src/contexts` |
|
||||
| `observability-vendors-live-behind-adapters` | code outside `src/adapters` | vendor telemetry SDKs |
|
||||
| `platform-kernel-is-product-neutral` | `src/platform`, except `routing/`, which reads app descriptors by type | features, contexts, apps, adapters, bootstrap, presentation, application |
|
||||
| `no-circular-dependencies` | all of `src` | import cycles |
|
||||
|
||||
The following edges are forbidden:
|
||||
|
||||
- domain to application, presentation, adapters, bootstrap, React, or browser globals
|
||||
- application to presentation, concrete adapters, bootstrap, React, or browser globals
|
||||
- `contracts` to application or features: contracts is the lower package and
|
||||
owns the shared vocabulary both of them read
|
||||
- presentation to concrete adapters, raw DTO schemas, or storage implementations
|
||||
- generic presentation to the installed-feature registries: which features exist
|
||||
is a product decision owned by `bootstrap`
|
||||
- an adapter to presentation, bootstrap internals, or another concrete adapter
|
||||
- feature domain/application to its presentation or outbound adapter, and
|
||||
feature presentation to its outbound adapter
|
||||
- a module presentation may import to a concrete adapter: files outside a
|
||||
feature's layer folders (`src/features/*.ts`, `src/features/<id>/*.ts`),
|
||||
`src/contexts` and `src/apps` (`feature-and-app-roots-do-not-reach-adapters`).
|
||||
The graph checks one edge at a time, so a re-export there would carry an
|
||||
adapter into presentation with every other rule passing. The one exception is
|
||||
the type-only `src/features/feature-adapter-contribution.ts`
|
||||
- presentation to `src/apps` or `src/contexts`, except
|
||||
`src/presentation/routes/app-router.tsx`, which mounts the app's route tree
|
||||
(`presentation-does-not-import-apps-or-contexts`)
|
||||
`feature-and-app-roots-do-not-reach-adapters` exists because the graph checks
|
||||
one edge at a time. Presentation may import those files, so a re-export of an
|
||||
adapter there would carry the adapter into presentation with every other rule
|
||||
passing.
|
||||
|
||||
## The adapter kernel
|
||||
|
||||
"Another concrete adapter" excludes the adapter kernel, which is shared on
|
||||
purpose and is the only adapter code an adapter may reach across a group for:
|
||||
`adapters-do-not-know-other-concrete-adapters` excludes the adapter kernel,
|
||||
which is shared on purpose and is the only adapter code an adapter may reach
|
||||
across a group for:
|
||||
|
||||
- `src/adapters/platform/**` — the system clock, the shared abort primitive and
|
||||
the bounded-capacity guard
|
||||
@@ -48,8 +88,12 @@ purpose and is the only adapter code an adapter may reach across a group for:
|
||||
invalidation transport and its types. Any adapter may import it; today
|
||||
`query-cache` does
|
||||
|
||||
Each rule above is enforced by `check:architecture`, including the kernel
|
||||
carve-out, so this table and the executable rules cannot drift apart.
|
||||
`check:architecture` enforces every rule above, including the kernel carve-out.
|
||||
`verify:documentation` fails when a rule name or a top-level `src` folder is
|
||||
missing from this page, when `README.md`, `overview.md` or
|
||||
`frontend-application-foundation.md` describe a folder differently from the
|
||||
folder table, and when any of them names a top-level `src` folder that does not
|
||||
exist. Neither checks that a row describes its rule correctly.
|
||||
|
||||
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
|
||||
exempted path in `pathNot`, and the reason, owner and revisit condition in
|
||||
@@ -63,6 +107,8 @@ exempted path in `pathNot`, and the reason, owner and revisit condition in
|
||||
- `src/presentation/routes/app-router.tsx` importing the app
|
||||
(`presentation-does-not-import-apps-or-contexts`)
|
||||
- the design-system facades (`design-system-is-reached-through-its-index`)
|
||||
- `src/platform/routing` reading deployable-app types
|
||||
(`platform-kernel-is-product-neutral`)
|
||||
|
||||
## 어댑터 그룹의 공개 경계
|
||||
|
||||
@@ -100,7 +146,8 @@ realm 파일만 빼는 구조라, 배럴이 그 파일을 다시 끌어들이면
|
||||
담당하고, 워커 진입점은 배럴을 쓰지 않는다.
|
||||
|
||||
`bootstrap` contains composition only. Business rules and page-specific
|
||||
orchestration belong to domain/application.
|
||||
orchestration belong to `src/application` or to a feature's domain and
|
||||
application.
|
||||
|
||||
The [ports, adapters, and feature-boundary contract](./frontend-ports-adapters-and-boundaries.md)
|
||||
explains how `presentation` acts as the inbound adapter and how feature
|
||||
|
||||
@@ -4,23 +4,43 @@ This Mermaid view is a repository-local implementation projection. The
|
||||
`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named
|
||||
in `review-ledger.json`, not automatically to edits in this file.
|
||||
|
||||
`src/` has nine top-level folders. The descriptions match the table in
|
||||
[the layer contract](./layers.md), which also names every import rule:
|
||||
|
||||
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
|
||||
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
|
||||
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
|
||||
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
|
||||
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
|
||||
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
|
||||
- `src/application` — generic use cases, ports, policies and view-models
|
||||
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
|
||||
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
|
||||
|
||||
Arrows point from the importing folder to the imported one. Every folder may
|
||||
also import `contracts` and `platform`; only the main path is drawn.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Bootstrap[bootstrap / composition root] --> Presentation[presentation]
|
||||
Bootstrap --> Adapters[adapters]
|
||||
Bootstrap --> Features[features]
|
||||
Presentation --> Shell[app shell and route surfaces]
|
||||
Shell --> Providers[session and theme providers]
|
||||
Presentation --> Application[application]
|
||||
Presentation -- app router only --> Apps[apps]
|
||||
Apps --> Contexts[contexts]
|
||||
Contexts --> Features
|
||||
Features --> Application[application]
|
||||
Presentation --> Application
|
||||
Adapters --> Application
|
||||
Application --> Domain[domain]
|
||||
Contracts[contract registries] --> Bootstrap
|
||||
Contracts --> Adapters
|
||||
Contracts --> Presentation
|
||||
Application --> Contracts[contracts]
|
||||
Contracts --> Platform[platform]
|
||||
```
|
||||
|
||||
The enforced dependency rule points inward: presentation calls application use
|
||||
cases, adapters implement application ports, and only the composition root
|
||||
selects concrete adapters. Contract registries are the named source for routes,
|
||||
selects concrete adapters. Domain code lives inside each feature. Contract
|
||||
registries are the named source for routes,
|
||||
API operations, environment values, storage keys, errors, queries, telemetry,
|
||||
and release tokens. Installed feature contributions extend those registries
|
||||
without making the generic application or router import a concrete feature
|
||||
|
||||
@@ -1409,6 +1409,18 @@ export const documentationReviewArtifactSchema = z
|
||||
routeScopeDocumented: z.boolean(),
|
||||
// 13-15: build and deploy variables README.md does not name.
|
||||
missingRuntimeVariables: z.array(nonEmptyString),
|
||||
// 1101/14-03: top-level src folders and architecture rules the entry
|
||||
// documents leave out, and top-level src folders they name that do not exist.
|
||||
sourceStructure: z.array(
|
||||
z
|
||||
.object({
|
||||
path: nonEmptyString,
|
||||
missingFolders: z.array(nonEmptyString),
|
||||
unknownFolders: z.array(nonEmptyString),
|
||||
missingRules: z.array(nonEmptyString),
|
||||
})
|
||||
.strict(),
|
||||
).min(1),
|
||||
results: z.array(
|
||||
z
|
||||
.object({
|
||||
@@ -1448,9 +1460,15 @@ export const documentationReviewArtifactSchema = z
|
||||
(artifact.reportDigestValid &&
|
||||
artifact.routeScopeDocumented &&
|
||||
artifact.missingRuntimeVariables.length === 0 &&
|
||||
artifact.sourceStructure.every(
|
||||
(entry) =>
|
||||
entry.missingFolders.length === 0 &&
|
||||
entry.unknownFolders.length === 0 &&
|
||||
entry.missingRules.length === 0,
|
||||
) &&
|
||||
artifact.results.every(({ passed }) => passed))
|
||||
) {
|
||||
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope and review results" });
|
||||
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure and review results" });
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { access, mkdir, readFile } from "node:fs/promises";
|
||||
import { access, mkdir, readdir, readFile } from "node:fs/promises";
|
||||
|
||||
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
|
||||
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
@@ -112,11 +112,64 @@ const missingRuntimeVariables = RUNTIME_VARIABLES.filter(
|
||||
(variable) => !readme.includes(`\`${variable}\``),
|
||||
);
|
||||
|
||||
// 1101/14-03. The entry documents drew a `src/domain` layer that does not
|
||||
// exist and left out `src/platform`, `src/apps` and `src/contexts`; layers.md
|
||||
// said its table "cannot drift" from the rules while most rule names were
|
||||
// missing. The folder and rule lists come from the code. layers.md describes
|
||||
// each folder in one table row, and the other entry documents repeat that
|
||||
// description verbatim as "`src/<folder>` — <description>", so a new folder or
|
||||
// rule must be documented, the descriptions cannot diverge, and no document
|
||||
// may name a top-level folder that is gone.
|
||||
const RULES_DOCUMENT = "docs/architecture/layers.md";
|
||||
const STRUCTURE_DOCUMENTS = Object.freeze([
|
||||
RULES_DOCUMENT,
|
||||
"README.md",
|
||||
"docs/architecture/overview.md",
|
||||
"docs/architecture/frontend-application-foundation.md",
|
||||
]);
|
||||
const repositoryRoot = new URL("../", import.meta.url);
|
||||
const sourceFolders = (await readdir(new URL("src/", repositoryRoot), { withFileTypes: true }))
|
||||
.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
|
||||
.map((entry) => entry.name)
|
||||
.sort();
|
||||
const architectureRules = (
|
||||
JSON.parse(await readFile(new URL(".dependency-cruiser.json", repositoryRoot), "utf8")) as {
|
||||
forbidden: readonly { name: string }[];
|
||||
}
|
||||
).forbidden.map((rule) => rule.name);
|
||||
const rulesText = await readFile(RULES_DOCUMENT, "utf8").catch(() => "");
|
||||
const folderDescriptions = new Map(
|
||||
[...rulesText.matchAll(/^\| `src\/([\w-]+)` \| (.+) \|$/gmu)].map((match) => [match[1], match[2]]),
|
||||
);
|
||||
const sourceStructure = [];
|
||||
for (const path of STRUCTURE_DOCUMENTS) {
|
||||
const text = path === RULES_DOCUMENT ? rulesText : await readFile(path, "utf8").catch(() => "");
|
||||
const namedFolders = new Set([...text.matchAll(/\bsrc\/([\w-]+)/gu)].map((match) => match[1] ?? ""));
|
||||
sourceStructure.push({
|
||||
path,
|
||||
missingFolders: sourceFolders.filter((folder) => {
|
||||
const description = folderDescriptions.get(folder);
|
||||
if (description === undefined) return true;
|
||||
return path !== RULES_DOCUMENT && !text.includes(`\`src/${folder}\` — ${description}`);
|
||||
}),
|
||||
unknownFolders: [...namedFolders].filter((folder) => !sourceFolders.includes(folder)).sort(),
|
||||
missingRules:
|
||||
path === RULES_DOCUMENT ? architectureRules.filter((rule) => !text.includes(`\`${rule}\``)) : [],
|
||||
});
|
||||
}
|
||||
const sourceStructureDocumented = sourceStructure.every(
|
||||
(entry) =>
|
||||
entry.missingFolders.length === 0 &&
|
||||
entry.unknownFolders.length === 0 &&
|
||||
entry.missingRules.length === 0,
|
||||
);
|
||||
|
||||
// 1101/14-06. Each failed check is named, so the stderr points at the file to
|
||||
// fix rather than at the diagram review whatever failed.
|
||||
const failedChecks = [
|
||||
...(routeScopeDocumented ? [] : ["route scope"]),
|
||||
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
|
||||
...(sourceStructureDocumented ? [] : ["source structure"]),
|
||||
...(reportDigestValid ? [] : ["review report digest"]),
|
||||
...(results.length === 2 && results.every((result) => result.passed)
|
||||
? []
|
||||
@@ -138,6 +191,7 @@ await writeValidatedJsonArtifact({
|
||||
routeScope,
|
||||
routeScopeDocumented,
|
||||
missingRuntimeVariables,
|
||||
sourceStructure,
|
||||
results,
|
||||
passed,
|
||||
},
|
||||
@@ -150,6 +204,19 @@ if (!passed) {
|
||||
if (missingRuntimeVariables.length > 0) {
|
||||
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
|
||||
}
|
||||
for (const entry of sourceStructure) {
|
||||
if (entry.missingFolders.length > 0) {
|
||||
process.stderr.write(`${entry.path} does not describe src folders as the layers.md table does: ${entry.missingFolders.join(", ")}\n`);
|
||||
}
|
||||
if (entry.unknownFolders.length > 0) {
|
||||
process.stderr.write(`${entry.path} names src folders that do not exist: ${entry.unknownFolders.join(", ")}\n`);
|
||||
}
|
||||
if (entry.missingRules.length > 0) {
|
||||
process.stderr.write(
|
||||
`${entry.path} does not name .dependency-cruiser.json rules: ${entry.missingRules.join(", ")}\n`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (!reportDigestValid) {
|
||||
process.stderr.write(
|
||||
`${ledger.evidenceReport.repoPath} does not contain the ledger's canonicalSha256\n`,
|
||||
|
||||
@@ -10,15 +10,18 @@ const INPUTS = [
|
||||
"docs/accessibility/manual-checklist.md",
|
||||
"docs/architecture/review-ledger.json",
|
||||
"docs/architecture/review-evidence.md",
|
||||
"docs/architecture/layers.md",
|
||||
"docs/architecture/overview.md",
|
||||
"docs/architecture/frontend-application-foundation.md",
|
||||
];
|
||||
|
||||
/** Runs verify:documentation on a copy of its inputs, `mutate` applied to README.md. */
|
||||
async function verifyWithReadme(mutate: (readme: string) => string) {
|
||||
/** Runs verify:documentation on a copy of its inputs, `mutate` applied to `document`. */
|
||||
async function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "documentation-readiness-"));
|
||||
try {
|
||||
for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true });
|
||||
const readme = path.join(root, "README.md");
|
||||
await writeFile(readme, mutate(await readFile(readme, "utf8")));
|
||||
const target = path.join(root, document);
|
||||
await writeFile(target, mutate(await readFile(target, "utf8")));
|
||||
return spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], {
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
@@ -53,3 +56,39 @@ describe("verify:documentation failure output (1101/14-06)", () => {
|
||||
expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u);
|
||||
});
|
||||
});
|
||||
|
||||
// 1101/14-03. The entry documents drew a top-level domain layer that does not
|
||||
// exist, left out three of the nine src folders, and layers.md named a
|
||||
// minority of the architecture rules while claiming it could not drift.
|
||||
describe("verify:documentation source structure (1101/14-03)", () => {
|
||||
it("fails when layers.md loses a rule name, as renaming a rule does", async () => {
|
||||
const result = await verifyWithReadme(
|
||||
(layers) => layers.replaceAll("`platform-kernel-is-product-neutral`", "`platform-kernel`"),
|
||||
"docs/architecture/layers.md",
|
||||
);
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(
|
||||
"docs/architecture/layers.md does not name .dependency-cruiser.json rules: platform-kernel-is-product-neutral",
|
||||
);
|
||||
expect(result.stderr).toMatch(/\(failed: source structure\)/u);
|
||||
});
|
||||
|
||||
it("fails when a document names a top-level src folder that does not exist", async () => {
|
||||
const result = await verifyWithReadme((readme) =>
|
||||
readme.replace("presentation -> application -> contracts", "presentation -> application -> `src/domain`"),
|
||||
);
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain("README.md names src folders that do not exist: domain");
|
||||
});
|
||||
|
||||
it("fails when a document describes a folder differently from layers.md", async () => {
|
||||
const result = await verifyWithReadme(
|
||||
(overview) => overview.replace("- `src/platform` — product-neutral", "- `src/platform` — shared"),
|
||||
"docs/architecture/overview.md",
|
||||
);
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(
|
||||
"docs/architecture/overview.md does not describe src folders as the layers.md table does: platform",
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user