From 61baf96682101854768df173ee009243586af2e4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 00:54:22 +0900 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=EC=9E=85=EA=B5=AC=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=EB=A5=BC=20=EC=8B=A4=EC=A0=9C=20src=20=ED=8F=B4?= =?UTF-8?q?=EB=8D=94=209=EA=B0=9C=EC=99=80=20=EA=B7=9C=EC=B9=99=20?= =?UTF-8?q?=EC=9D=B4=EB=A6=84=EC=97=90=20=EB=A7=9E=EC=B6=94=EA=B3=A0=20?= =?UTF-8?q?=EA=B2=80=EC=82=AC=ED=95=9C=EB=8B=A4=20(14-03)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 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 --- README.md | 21 +++- docs/architecture/contract-ownership.md | 14 +++ .../frontend-application-foundation.md | 23 +++- docs/architecture/layers.md | 119 ++++++++++++------ docs/architecture/overview.md | 32 ++++- scripts/contracts/release-artifacts.ts | 20 ++- scripts/verify-documentation-readiness.ts | 69 +++++++++- tests/unit/documentation-readiness.test.ts | 47 ++++++- 8 files changed, 290 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index f8b9cea5..422214a4 100644 --- a/README.md +++ b/README.md @@ -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//{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 diff --git a/docs/architecture/contract-ownership.md b/docs/architecture/contract-ownership.md index fec11dee..270956b5 100644 --- a/docs/architecture/contract-ownership.md +++ b/docs/architecture/contract-ownership.md @@ -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 diff --git a/docs/architecture/frontend-application-foundation.md b/docs/architecture/frontend-application-foundation.md index 60fc15c1..5ecc6466 100644 --- a/docs/architecture/frontend-application-foundation.md +++ b/docs/architecture/frontend-application-foundation.md @@ -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//{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`) + +Inside one feature: + - `features//domain` - `features//application` - `features//contracts` diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index 007b3bc2..973e6e6a 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -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//{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//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/` | 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//domain` | application, presentation, adapters, bootstrap, any feature's application, adapters and presentation, React, TanStack | +| `feature-application-does-not-know-runtime` | `src/features//application` | presentation, adapters, bootstrap, any feature's adapters and presentation, React, TanStack | +| `feature-presentation-does-not-know-outbound-adapters` | `src/features//presentation` | adapters, bootstrap, any feature's adapters, TanStack | +| `feature-adapters-do-not-know-presentation` | `src/features//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//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//*.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//*.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 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 9f8579db..7750dc2b 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -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//{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 diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index 090869e1..6d2f9c54 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -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" }); } }); diff --git a/scripts/verify-documentation-readiness.ts b/scripts/verify-documentation-readiness.ts index 4cebe964..8aec9db6 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -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/` — ", 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`, diff --git a/tests/unit/documentation-readiness.test.ts b/tests/unit/documentation-readiness.test.ts index 55f677dc..5eeb3a7d 100644 --- a/tests/unit/documentation-readiness.test.ts +++ b/tests/unit/documentation-readiness.test.ts @@ -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", + ); + }); +});