donghyeon.kang/clean-architecture-frontend-template
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

merge: test and registry evidence hardening

Browse Source
This commit is contained in:
donghyeon-ka
2026-07-26 17:15:32 +09:00
parent 3f634eb655 98d4fd4960
commit a64708f3de
68 changed files with 6167 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -10,4 +10,7 @@ artifacts/**/*.xml
artifacts/**/*.txt artifacts/**/*.txt
artifacts/**/*.sarif artifacts/**/*.sarif
artifacts/tests/e2e/ artifacts/tests/e2e/
artifacts/storybook/
artifacts/tests/storybook/
artifacts/tests/visual/
!artifacts/**/.gitkeep !artifacts/**/.gitkeep
.storybook/main.ts
+15
View File
@@ -0,0 +1,15 @@
import type { StorybookConfig } from "@storybook/react-vite";
const config: StorybookConfig = {
stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
addons: ["@storybook/addon-a11y"],
framework: {
name: "@storybook/react-vite",
options: {},
},
core: {
disableTelemetry: true,
},
};
export default config;
.storybook/preview.tsx
+88
View File
@@ -0,0 +1,88 @@
import type { Preview } from "@storybook/react-vite";
import { QueryClientProvider } from "@tanstack/react-query";
import { MemoryRouter } from "react-router-dom";
import { createAnonymousSessionAdapter } from "../src/adapters/auth/external-session-adapter.js";
import { createQueryClient } from "../src/adapters/query-cache/tanstack-query-cache.js";
import { createApplication } from "../src/application/create-application.js";
import { LocaleProvider } from "../src/presentation/i18n/index.js";
import { ApplicationProvider } from "../src/presentation/providers/application-provider.js";
import { SessionProvider } from "../src/presentation/providers/session-provider.jsx";
import { ThemeProvider } from "../src/presentation/providers/theme-provider.jsx";
import "../src/presentation/styles/theme.css";
const preferences = new Map<string, unknown>();
const application = createApplication({
session: createAnonymousSessionAdapter(),
preferences: {
read: (name) => ({ ok: true, value: preferences.get(name) }),
write: (name, value) => {
preferences.set(name, structuredClone(value));
return { ok: true };
},
remove: (name) => {
preferences.delete(name);
return { ok: true };
},
},
diagnostics: { record() {} },
telemetry: { emit() {} },
releaseInfo: {
getCurrent: async () => ({
buildId: "storybook-build",
releaseId: "storybook-release",
configSchemaVersion: "1",
apiContractVersion: "1",
assetManifestHash: "storybook-assets",
routeChunks: {},
}),
refresh: async () => ({
buildId: "storybook-build",
releaseId: "storybook-release",
configSchemaVersion: "1",
apiContractVersion: "1",
assetManifestHash: "storybook-assets",
routeChunks: {},
}),
},
navigation: { reload() {} },
});
const queryClient = createQueryClient();
const preview: Preview = {
decorators: [
(Story) => (
<ApplicationProvider application={application}>
<QueryClientProvider client={queryClient}>
<MemoryRouter>
<LocaleProvider>
<ThemeProvider>
<SessionProvider>
<div id="portal-root" />
<main className="ui-page" style={{ padding: "1rem" }}>
<Story />
</main>
</SessionProvider>
</ThemeProvider>
</LocaleProvider>
</MemoryRouter>
</QueryClientProvider>
</ApplicationProvider>
),
],
parameters: {
a11y: {
test: "error",
},
controls: {
expanded: true,
},
options: {
storySort: {
order: ["Platform"],
},
},
},
};
export default preview;
config/ci/gates.json
+42 -6
View File
@@ -100,9 +100,19 @@
}, },
"FE-GATE-005": { "FE-GATE-005": {
"name": "unit", "name": "unit",
"steps": [{ "script": "test:unit", "expect": "pass" }], "steps": [
{ "script": "test:unit", "expect": "pass" },
{ "script": "test:coverage", "expect": "pass" },
{ "script": "check:coverage:fixture", "expect": "fail" }
],
"logPath": "artifacts/quality/gates/FE-GATE-005.txt", "logPath": "artifacts/quality/gates/FE-GATE-005.txt",
"evidence": ["artifacts/tests/unit.xml"], "evidence": [
"artifacts/tests/unit.xml",
"artifacts/tests/coverage.xml",
"artifacts/tests/coverage/coverage-summary.json",
"artifacts/quality/risk-coverage.json",
"artifacts/quality/risk-coverage-fixture.json"
],
"retentionClass": "merge-cycle" "retentionClass": "merge-cycle"
}, },
"FE-GATE-006": { "FE-GATE-006": {
@@ -127,9 +137,24 @@
}, },
"FE-GATE-008": { "FE-GATE-008": {
"name": "e2e", "name": "e2e",
"steps": [{ "script": "test:e2e", "expect": "pass" }], "steps": [
{ "script": "test:e2e", "expect": "pass" },
{ "script": "test:storybook", "expect": "pass" },
{ "script": "test:visual", "expect": "pass" },
{ "script": "check:test-evidence", "expect": "pass" },
{ "script": "check:test-evidence:fixture", "expect": "fail" }
],
"logPath": "artifacts/quality/gates/FE-GATE-008.txt", "logPath": "artifacts/quality/gates/FE-GATE-008.txt",
"evidence": ["artifacts/tests/e2e/report/index.html"], "evidence": [
"artifacts/tests/e2e/report/index.html",
"artifacts/tests/e2e/results.xml",
"artifacts/tests/storybook/report/index.html",
"artifacts/tests/storybook/results.xml",
"artifacts/tests/visual/report/index.html",
"artifacts/tests/visual/results.xml",
"artifacts/quality/test-evidence.json",
"artifacts/quality/test-evidence-fixture.json"
],
"retentionClass": "merge-cycle" "retentionClass": "merge-cycle"
}, },
"FE-GATE-009": { "FE-GATE-009": {
@@ -162,6 +187,11 @@
{ "script": "check:diagnostics", "expect": "pass" }, { "script": "check:diagnostics", "expect": "pass" },
{ "script": "check:diagnostics:fixture", "expect": "fail" }, { "script": "check:diagnostics:fixture", "expect": "fail" },
{ "script": "check:registries", "expect": "pass" }, { "script": "check:registries", "expect": "pass" },
{
"script": "check:registries:compatibility-fixtures",
"expect": "pass"
},
{ "script": "check:registries:baseline-fixture", "expect": "fail" },
{ "script": "check:registries:fixture", "expect": "fail" }, { "script": "check:registries:fixture", "expect": "fail" },
{ "script": "check:routes:fixture", "expect": "fail" } { "script": "check:routes:fixture", "expect": "fail" }
], ],
@@ -175,6 +205,8 @@
"artifacts/quality/diagnostics.json", "artifacts/quality/diagnostics.json",
"artifacts/quality/diagnostics-fixture.json", "artifacts/quality/diagnostics-fixture.json",
"artifacts/quality/registries.json", "artifacts/quality/registries.json",
"artifacts/quality/registry-compatibility-fixtures.json",
"artifacts/quality/registry-baseline-fixture.json",
"artifacts/quality/registry-fixture.json", "artifacts/quality/registry-fixture.json",
"artifacts/quality/route-registry-fixture.json" "artifacts/quality/route-registry-fixture.json"
], ],
@@ -182,11 +214,15 @@
}, },
"FE-GATE-011": { "FE-GATE-011": {
"name": "build", "name": "build",
"steps": [{ "script": "build", "expect": "pass" }], "steps": [
{ "script": "build", "expect": "pass" },
{ "script": "build:storybook", "expect": "pass" }
],
"logPath": "artifacts/quality/gates/FE-GATE-011.txt", "logPath": "artifacts/quality/gates/FE-GATE-011.txt",
"evidence": [ "evidence": [
"artifacts/release/build-manifest.json", "artifacts/release/build-manifest.json",
"artifacts/release/runtime-config.schema.json" "artifacts/release/runtime-config.schema.json",
"artifacts/storybook/static/index.html"
], ],
"retentionClass": "release-coherence" "retentionClass": "release-coherence"
}, },
config/contracts/registry-baseline.approval.json
+7
View File
@@ -0,0 +1,7 @@
{
"schemaVersion": 1,
"snapshotDigest": "e8448e46bc65326e9b2eb23cdce0870242faedb7a354942389c4a95b0e392d90",
"owner": "frontend-platform",
"reason": "RP-10 initial approved executable registry baseline",
"approvedAt": "2026-07-26T07:53:45.969Z"
}
config/contracts/registry-baseline.json
+1701
View File
File diff suppressed because it is too large Load Diff
config/contracts/registry-change-evidence.json
+4
View File
@@ -0,0 +1,4 @@
{
"schemaVersion": 1,
"changes": []
}
config/contracts/registry-governance.json
+328 -42
View File
@@ -1,13 +1,46 @@
{ {
"schemaVersion": 1, "schemaVersion": 2,
"sourceDirectories": [
"src/application",
"src/presentation",
"src/domain"
],
"registries": [ "registries": [
{ {
"registryId": "FE-REG-ROUTE", "registryId": "FE-REG-ROUTE",
"path": "src/features/installed-feature-contracts.js", "path": "src/features/installed-feature-contracts.js",
"exportName": "ROUTE_REGISTRY", "exportName": "ROUTE_REGISTRY",
"owner": "feature-routing-navigation-guard-contract", "owner": "feature-frontend-routing-release-recovery-runtime",
"keyField": "routeId",
"requiredFields": [
"routeId",
"path",
"paramsSchema",
"searchSchema",
"access",
"loadingSurface",
"errorSurface",
"chunkId",
"title",
"navigationLabel",
"navigationOrder"
],
"fieldTypes": {
"routeId": "string",
"path": "string",
"paramsSchema": "string|null",
"searchSchema": "string|null",
"access": "string",
"loadingSurface": "string",
"errorSurface": "string",
"chunkId": "string",
"title": "string",
"navigationLabel": "string|null",
"navigationOrder": "integer|null"
},
"uniqueFields": ["routeId", "path", "chunkId"], "uniqueFields": ["routeId", "path", "chunkId"],
"allowedValues": { "allowedValues": {
"access": ["public", "session-required", "integration-defined"],
"paramsSchema": [null, "NotFoundSplat", "ReferenceResourceParams"], "paramsSchema": [null, "NotFoundSplat", "ReferenceResourceParams"],
"searchSchema": [null, "ReferenceResourceListQuery"], "searchSchema": [null, "ReferenceResourceListQuery"],
"loadingSurface": [ "loadingSurface": [
@@ -23,17 +56,6 @@
"route-boundary", "route-boundary",
"feature-boundary", "feature-boundary",
"not-found" "not-found"
],
"chunkId": [
"route-home",
"route-examples-ui",
"route-examples-states",
"route-examples-auth",
"route-reference-resources",
"route-reference-resource-detail",
"route-reference-resource-form",
"route-reference-resource-status",
"route-not-found"
] ]
}, },
"references": [ "references": [
@@ -41,16 +63,30 @@
"field": "routeId", "field": "routeId",
"registryId": "FE-REG-ROUTE-RUNTIME", "registryId": "FE-REG-ROUTE-RUNTIME",
"targetField": "routeId" "targetField": "routeId"
},
{
"field": "paramsSchema",
"registryId": "FE-REG-SCHEMA",
"targetField": "schemaId"
},
{
"field": "searchSchema",
"registryId": "FE-REG-SCHEMA",
"targetField": "schemaId"
} }
], ],
"requiredFields": [ "consumers": [
{
"path": "src/presentation/routes/app-router.tsx",
"token": "ROUTE_REGISTRY"
}
],
"breakingFields": [
"routeId", "routeId",
"path", "path",
"paramsSchema", "paramsSchema",
"searchSchema", "searchSchema",
"access", "access",
"loadingSurface",
"errorSurface",
"chunkId" "chunkId"
] ]
}, },
@@ -59,41 +95,56 @@
"path": "src/features/installed-feature-contracts.js", "path": "src/features/installed-feature-contracts.js",
"exportName": "ROUTE_RUNTIME_CONTRACT", "exportName": "ROUTE_RUNTIME_CONTRACT",
"owner": "feature-frontend-routing-release-recovery-runtime", "owner": "feature-frontend-routing-release-recovery-runtime",
"keyField": "routeId",
"requiredFields": [ "requiredFields": [
"routeId", "routeId",
"moduleId", "moduleId",
"paramsCodec", "paramsCodec",
"searchCodec" "searchCodec"
], ],
"uniqueFields": ["routeId", "moduleId"], "fieldTypes": {
"allowedValues": { "routeId": "string",
"moduleId": [ "moduleId": "string",
"home-page", "paramsCodec": "string",
"ui-gallery-page", "searchCodec": "string"
"state-gallery-page",
"auth-example-page",
"reference-resource-page",
"reference-resource-detail-page",
"reference-resource-form-page",
"reference-resource-status-page",
"not-found-page"
],
"paramsCodec": ["none", "NotFoundSplat", "ReferenceResourceParams"],
"searchCodec": ["none", "ReferenceResourceListQuery"]
}, },
"uniqueFields": ["routeId", "moduleId"],
"references": [ "references": [
{ {
"field": "routeId", "field": "routeId",
"registryId": "FE-REG-ROUTE", "registryId": "FE-REG-ROUTE",
"targetField": "routeId" "targetField": "routeId"
},
{
"field": "paramsCodec",
"registryId": "FE-REG-SCHEMA",
"targetField": "schemaId"
},
{
"field": "searchCodec",
"registryId": "FE-REG-SCHEMA",
"targetField": "schemaId"
} }
],
"consumers": [
{
"path": "src/presentation/routes/route-codecs.ts",
"token": "ROUTE_RUNTIME_CONTRACT"
}
],
"breakingFields": [
"routeId",
"moduleId",
"paramsCodec",
"searchCodec"
] ]
}, },
{ {
"registryId": "FE-REG-API", "registryId": "FE-REG-API",
"path": "src/features/installed-feature-contracts.js", "path": "src/features/installed-feature-contracts.js",
"exportName": "API_OPERATIONS", "exportName": "API_OPERATIONS",
"owner": "feature-api-client-response-envelope-contract", "owner": "feature-frontend-api-client-response-envelope-contract",
"keyField": "operationId",
"requiredFields": [ "requiredFields": [
"method", "method",
"path", "path",
@@ -106,20 +157,127 @@
"requestSchema", "requestSchema",
"responseSchema", "responseSchema",
"owner" "owner"
],
"fieldTypes": {
"method": "string",
"path": "string",
"operationId": "string",
"auth": "string",
"timeoutMs": "integer|null",
"idempotency": "string",
"retry": "string",
"requestSource": "string",
"requestSchema": "string",
"responseSchema": "string",
"owner": "string"
},
"uniqueFields": ["operationId"],
"allowedValues": {
"method": ["GET", "POST", "PUT", "PATCH", "DELETE"],
"auth": ["none", "external-session"],
"idempotency": ["safe", "keyed", "none"],
"retry": ["runtime", "never"],
"requestSource": ["none", "search", "body"]
},
"references": [
{
"field": "requestSchema",
"registryId": "FE-REG-SCHEMA",
"targetField": "schemaId"
},
{
"field": "responseSchema",
"registryId": "FE-REG-SCHEMA",
"targetField": "schemaId"
}
],
"consumerIdentityField": "operationId",
"consumerDirectories": [
"src/features/reference-feature/adapters",
"src/features/reference-feature/application"
],
"breakingFields": [
"method",
"path",
"operationId",
"auth",
"idempotency",
"requestSource",
"requestSchema",
"responseSchema"
] ]
}, },
{
"registryId": "FE-REG-SCHEMA",
"path": "src/features/installed-feature-contracts.js",
"exportName": "SCHEMA_REGISTRY",
"owner": "feature-frontend-contract-schema-registry",
"keyField": "schemaId",
"requiredFields": ["schemaId", "boundary", "owner", "runtime"],
"fieldTypes": {
"schemaId": "string",
"boundary": "string",
"owner": "string",
"runtime": "string"
},
"uniqueFields": ["schemaId"],
"allowedValues": {
"boundary": [
"route-params",
"route-search",
"route-search-api-request",
"api-request",
"api-response"
],
"runtime": ["zod"]
},
"consumerIdentityField": "schemaId",
"consumerDirectories": [
"src/presentation/routes",
"src/features/reference-feature/presentation",
"src/features/reference-feature/contracts"
],
"breakingFields": ["schemaId", "boundary", "runtime"]
},
{ {
"registryId": "FE-REG-ENV", "registryId": "FE-REG-ENV",
"path": "src/contracts/env.js", "path": "src/contracts/env.js",
"exportName": "ENV_REGISTRY", "exportName": "ENV_REGISTRY",
"owner": "feature-frontend-env-runtime-config-contract", "owner": "feature-frontend-env-runtime-config-contract",
"requiredFields": ["phase", "classification", "required", "defaultValue"] "requiredFields": ["phase", "classification", "required", "defaultValue"],
"fieldTypes": {
"phase": "string",
"classification": "string",
"required": "boolean",
"defaultValue": "string|integer|boolean|null"
},
"allowedValues": {
"phase": ["build", "runtime"],
"classification": [
"public",
"public-sensitive",
"public-metadata",
"compile-time"
]
},
"consumers": [
{
"path": "src/bootstrap/runtime-config-schema.js",
"token": "APP_ENV"
},
{
"path": "src/contracts/env.js",
"token": "getBuildConfig"
}
],
"breakingFields": ["phase", "classification", "required"]
}, },
{ {
"registryId": "FE-REG-STORAGE", "registryId": "FE-REG-STORAGE",
"path": "src/contracts/storage-keys.js", "path": "src/contracts/storage-keys.js",
"exportName": "STORAGE_REGISTRY", "exportName": "STORAGE_REGISTRY",
"owner": "feature-frontend-storage-registry-contract", "owner": "feature-frontend-storage-registry-contract",
"keyField": "logicalName",
"requiredFields": [ "requiredFields": [
"logicalName", "logicalName",
"physicalKey", "physicalKey",
@@ -129,6 +287,44 @@
"ttl", "ttl",
"migration", "migration",
"quotaFallback" "quotaFallback"
],
"fieldTypes": {
"logicalName": "string",
"physicalKey": "string",
"backend": "string",
"classification": "string",
"schemaVersion": "integer",
"ttl": "integer|string|null",
"migration": "string|function",
"quotaFallback": "string"
},
"uniqueFields": ["logicalName", "physicalKey"],
"allowedValues": {
"backend": [
"memory",
"sessionStorage",
"localStorage",
"indexedDB",
"disabled",
"forbidden"
],
"classification": [
"public-preference",
"opaque-cache",
"sensitive-forbidden"
],
"quotaFallback": ["memory", "no-persist", "feature-disable"]
},
"consumerIdentityField": "logicalName",
"consumerDirectories": ["src", "tests"],
"orphanExemptRows": ["QUERY_PERSISTENCE", "AUTH_TOKEN"],
"breakingFields": [
"logicalName",
"physicalKey",
"backend",
"classification",
"schemaVersion",
"migration"
] ]
}, },
{ {
@@ -136,6 +332,7 @@
"path": "src/contracts/errors.js", "path": "src/contracts/errors.js",
"exportName": "ERROR_REGISTRY", "exportName": "ERROR_REGISTRY",
"owner": "feature-frontend-error-classification-boundary-contract", "owner": "feature-frontend-error-classification-boundary-contract",
"keyField": "kind",
"requiredFields": [ "requiredFields": [
"kind", "kind",
"defaultRetryable", "defaultRetryable",
@@ -144,13 +341,41 @@
"action", "action",
"telemetryEvent", "telemetryEvent",
"redaction" "redaction"
] ],
"fieldTypes": {
"kind": "string",
"defaultRetryable": "boolean",
"severity": "string",
"userMessageKey": "string",
"action": "string",
"telemetryEvent": "string",
"redaction": "array"
},
"uniqueFields": ["kind"],
"allowedValues": {
"severity": ["info", "warning", "error"],
"action": [
"retry",
"reauth",
"navigate",
"reload-once",
"contact-support",
"none"
]
},
"consumers": [
{
"path": "src/adapters/http/client.js",
"token": "failure("
}
],
"breakingFields": ["kind", "userMessageKey", "action", "telemetryEvent"]
}, },
{ {
"registryId": "FE-REG-QUERY", "registryId": "FE-REG-QUERY",
"path": "src/features/installed-feature-contracts.js", "path": "src/features/installed-feature-contracts.js",
"exportName": "QUERY_REGISTRY", "exportName": "QUERY_REGISTRY",
"owner": "feature-server-state-caching-contract", "owner": "feature-frontend-server-state-caching-contract",
"requiredFields": [ "requiredFields": [
"namespace", "namespace",
"serialization", "serialization",
@@ -158,13 +383,39 @@
"invalidation", "invalidation",
"version", "version",
"persistence" "persistence"
],
"fieldTypes": {
"namespace": "array",
"serialization": "string",
"identity": "string",
"invalidation": "string",
"version": "integer",
"persistence": "string"
},
"uniqueFields": ["namespace"],
"allowedValues": {
"persistence": ["disabled"]
},
"consumers": [
{
"path": "src/features/reference-feature/contracts/reference-feature-contract.js",
"token": "referenceQueryKeys"
}
],
"breakingFields": [
"namespace",
"serialization",
"identity",
"version",
"persistence"
] ]
}, },
{ {
"registryId": "FE-REG-TELEMETRY", "registryId": "FE-REG-TELEMETRY",
"path": "src/contracts/telemetry.js", "path": "src/contracts/telemetry.js",
"exportName": "TELEMETRY_REGISTRY", "exportName": "TELEMETRY_REGISTRY",
"owner": "feature-frontend-observability-logging-trace-contract", "owner": "feature-frontend-diagnostics-telemetry-runtime",
"keyField": "eventName",
"requiredFields": [ "requiredFields": [
"eventName", "eventName",
"trigger", "trigger",
@@ -173,6 +424,31 @@
"forbiddenAttributes", "forbiddenAttributes",
"sampling", "sampling",
"delivery" "delivery"
],
"fieldTypes": {
"eventName": "string",
"trigger": "string",
"requiredAttributes": "array",
"optionalAttributes": "array",
"forbiddenAttributes": "array",
"sampling": "string",
"delivery": "string"
},
"uniqueFields": ["eventName"],
"allowedValues": {
"delivery": ["best-effort"]
},
"consumers": [
{
"path": "scripts/check-diagnostics.mjs",
"token": "TELEMETRY_REGISTRY"
}
],
"breakingFields": [
"eventName",
"requiredAttributes",
"forbiddenAttributes",
"delivery"
] ]
}, },
{ {
@@ -180,11 +456,21 @@
"path": "src/contracts/release-tokens.js", "path": "src/contracts/release-tokens.js",
"exportName": "RELEASE_TOKEN_REGISTRY", "exportName": "RELEASE_TOKEN_REGISTRY",
"owner": "feature-frontend-release-cache-rollback-contract", "owner": "feature-frontend-release-cache-rollback-contract",
"requiredFields": ["token", "source", "compatibilityRole"] "keyField": "token",
"requiredFields": ["token", "source", "compatibilityRole"],
"fieldTypes": {
"token": "string",
"source": "string",
"compatibilityRole": "string"
},
"uniqueFields": ["token"],
"consumers": [
{
"path": "src/bootstrap/load-release-manifest.js",
"token": "assetManifestHash"
}
],
"breakingFields": ["token", "source", "compatibilityRole"]
} }
], ]
"compatibilityImpact": {
"allowed": ["none", "additive", "behavior-change", "breaking"],
"current": "behavior-change"
}
} }
config/testing/risk-coverage.json
+92
View File
@@ -0,0 +1,92 @@
{
"schemaVersion": 1,
"summary": {
"lines": 80,
"statements": 78,
"functions": 85,
"branches": 68
},
"criticalModules": [
{
"path": "src/adapters/http/retry-policy.js",
"minimum": {
"lines": 80,
"statements": 78,
"functions": 95,
"branches": 78
}
},
{
"path": "src/adapters/storage/browser-storage-adapter.js",
"minimum": {
"lines": 60,
"statements": 60,
"functions": 70,
"branches": 60
}
},
{
"path": "src/adapters/telemetry/best-effort-telemetry.js",
"minimum": {
"lines": 85,
"statements": 85,
"functions": 70,
"branches": 75
}
},
{
"path": "src/application/policies/compatibility.js",
"minimum": {
"lines": 95,
"statements": 95,
"functions": 95,
"branches": 75
}
},
{
"path": "src/application/policies/performance-budgets.js",
"minimum": {
"lines": 80,
"statements": 80,
"functions": 80,
"branches": 40
}
},
{
"path": "src/application/policies/promotion-readiness.js",
"minimum": {
"lines": 95,
"statements": 95,
"functions": 95,
"branches": 95
}
},
{
"path": "src/application/use-cases/decide-chunk-recovery.js",
"minimum": {
"lines": 90,
"statements": 90,
"functions": 95,
"branches": 85
}
},
{
"path": "src/contracts/diagnostics.ts",
"minimum": {
"lines": 68,
"statements": 68,
"functions": 95,
"branches": 58
}
},
{
"path": "scripts/lib/registry-compatibility.mjs",
"minimum": {
"lines": 80,
"statements": 80,
"functions": 85,
"branches": 60
}
}
]
}
docs/architecture/decisions/VD-08-storybook-and-visual-evidence.md
+71
View File
@@ -0,0 +1,71 @@
# VD-08: 개발용 Storybook과 로컬 시각 회귀 증적
- 상태: Accepted
- 결정일: 2026-07-26
- 적용 브랜치: `feature-frontend-test-registry-evidence-hardening`
- 재검토: 제품이 cloud visual review, 다중 OS baseline 또는 별도 디자인 시스템
배포를 요구할 때
## 배경
`/examples/ui`와 `/examples/states`는 실제 application composition 안에서 공통
UI와 상태 표면을 보여 주지만, primitive를 격리해 interaction과 접근성을 검증하는
workshop은 아니었다. 실패 시 screenshot도 디버깅 증거일 뿐 의도된 UI 기준선과
현재 렌더의 차이를 차단하지 못했다.
외부 visual review 서비스, 별도 Storybook 배포와 브랜드별 baseline은 아직
선정되지 않았다. 이 결정을 기다리며 UI 회귀 검증을 비워 두거나 production
application bundle에 workshop runtime을 포함하는 것 모두 적절하지 않다.
## 결정
1. Storybook은 development dependency와 별도 static artifact로만 사용한다.
production entry와 application `dist`에는 Storybook runtime, story 또는
테스트 selector를 포함하지 않는다.
2. story는 public design-system entry를 소비하고 실제 locale, theme, session,
router와 query provider 계약으로 렌더한다. production component를 복제한
story 전용 구현을 만들지 않는다.
3. interaction과 story-level axe는 Playwright가 정적 Storybook을 대상으로
실행한다. unexpected console, page error와 request failure는 테스트 실패다.
4. 시각 회귀는 production `build` 후 `preview`를 대상으로 pinned Chromium,
locale, color scheme과 viewport에서 `toHaveScreenshot()`으로 실행한다.
5. 최초 기준선은 wide shell, compact pseudo-locale drawer, dark design-system
gallery, loading/empty/error/access 상태 표면을 포함한다.
6. animation과 caret만 결정적으로 비활성화한다. `html`, `body`, `main` 또는
application 전체를 mask해 false PASS를 만드는 설정은 gate가 거절한다.
7. snapshot 갱신은 `test:visual:update`라는 명시적 명령으로 분리하고 PNG diff를
review한다. 일반 `test:visual`은 승인 기준선을 변경하지 않는다.
8. local visual threshold는 작은 rasterization 차이만 허용하며 실제 layout,
copy, theme 또는 상태 변화가 숨겨지도록 확대하지 않는다.
9. `/examples/*`는 production composition smoke로 유지하고 Storybook story의
대체물로 취급하지 않는다. 반대로 Storybook만 통과해 application shell
integration을 완료 처리하지 않는다.
10. cloud service가 선정되지 않아도 repository-local workshop, interaction,
a11y와 visual baseline gate는 완전하게 실행 가능해야 한다.
## 실행과 증적
- workshop config: `.storybook/main.ts`, `.storybook/preview.tsx`
- story: `src/presentation/design-system/design-system.stories.tsx`
- interaction/a11y: `tests/storybook/workshop.spec.ts`
- visual: `tests/visual/platform.visual.spec.ts`
- baseline: `tests/visual/__snapshots__/`
- production E2E: `playwright.config.js`
- local dev E2E: `playwright.dev.config.js`
- evidence policy: `scripts/check-test-evidence.mjs`
CI는 JUnit, HTML report, failure trace/screenshot, visual baseline 존재 여부와
금지된 full-screen mask/무소유 skip fixture를 함께 검사한다.
## 한계와 재검토 조건
로컬 기준선은 실제 iOS/Android 기기, 여러 운영체제의 font rasterization,
디자인 승인 workflow와 다중 브랜드를 증명하지 않는다. 이를 요구하면 동일
public component와 story를 입력으로 사용하는 외부 review adapter를 추가하되,
provider 결과가 없을 때 임의 PASS로 대체하지 않는다.
## Rollback
Storybook dependency/config, workshop test와 visual config/baseline은 production
runtime 변경 없이 독립적으로 제거할 수 있다. rollback 후에도 `/examples/*`,
component behavior, automated accessibility와 built-dist E2E는 유지한다.
docs/architecture/frontend-platform-capability-review.md
+12 -11
View File
@@ -12,7 +12,7 @@
- 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다. - 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다.
- 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다. - 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다.
최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-08 구현 결과를 이 문서에 최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-10 구현 결과를 이 문서에
누적 반영했다. 이후 구현으로 경로나 세부 내용이 달라질 수 있으므로, 각 항목은 누적 반영했다. 이후 구현으로 경로나 세부 내용이 달라질 수 있으므로, 각 항목은
문서의 경로뿐 아니라 해당 테스트와 아키텍처 게이트로 계속 검증해야 한다. 문서의 경로뿐 아니라 해당 테스트와 아키텍처 게이트로 계속 검증해야 한다.
@@ -39,15 +39,16 @@ recovery 계약, 제거 가능한 reference 수직 슬라이스, form/page, desi
i18n 실행 경계와 diagnostics/telemetry production wiring은 구현됐다. 현재 선행 해결 i18n 실행 경계와 diagnostics/telemetry production wiring은 구현됐다. 현재 선행 해결
대상은 다음과 같다. 대상은 다음과 같다.
1. registry evidence와 실제 compatibility diff 1. 공급망의 transitive inventory/license/vulnerability/SBOM/provenance 검증
2. 공급망과 optional adapter recipe 심화 게이트 2. optional adapter의 opt-in 경계와 제거 가능한 recipe
따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다. 따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다.
더 정확한 표현은 다음과 같다. 더 정확한 표현은 다음과 같다.
> 운영·안전 계약과 범용 앱 셸은 갖춰졌지만, 기능 개발자가 사용하는 application > application API, 서버 상태, 폼, 라우팅, 페이지, 디자인 시스템과 테스트 증적의
> API, 서버 상태, 폼, 라우팅, 페이지 패턴의 표준 수직 경로는 아직 보강이 > 표준 수직 경로는 갖춰졌다. 현재 남은 저장소 내부 범위는 공급망 검증과
> 필요하다. > opt-in adapter recipe이며 실제 hosting·IdP·운영 provider는 프로젝트 통합
> 범위다.
## 3. 판정 기준 ## 3. 판정 기준
@@ -77,17 +78,17 @@ i18n 실행 경계와 diagnostics/telemetry production wiring은 구현됐다.
| 앱 셸·반응형 | 준비됨 | native modal Drawer, compact/desktop layout, Escape/link dismiss/focus restore, pseudo reflow와 RTL direction | compact browser matrix 유지 | | 앱 셸·반응형 | 준비됨 | native modal Drawer, compact/desktop layout, Escape/link dismiss/focus restore, pseudo reflow와 RTL direction | compact browser matrix 유지 |
| 페이지 템플릿 | 준비됨 | Standard/Collection/Detail/Form/Status와 public design-system entry | feature별 slot 조합 유지 | | 페이지 템플릿 | 준비됨 | Standard/Collection/Detail/Form/Status와 public design-system entry | feature별 slot 조합 유지 |
| 디자인 토큰 | 준비됨 | primitive/semantic/component CSS, 48-token 자동 계약, dark/forced-colors/reduced-motion | 제품 brand token은 외부 프로젝트에서 확장 | | 디자인 토큰 | 준비됨 | primitive/semantic/component CSS, 48-token 자동 계약, dark/forced-colors/reduced-motion | 제품 brand token은 외부 프로젝트에서 확장 |
| 공통 UI | 준비됨 | action/form/feedback/overlay/navigation primitive와 pattern, compatibility export | Storybook/visual은 RP-10 | | 공통 UI | 준비됨 | action/form/feedback/overlay/navigation primitive와 pattern, compatibility export | public story와 visual state matrix 유지 |
| 아이콘 | 준비됨 | Lucide static vendor facade와 semantic icon/IconButton 접근성 계약 | 의미 icon 추가 시 bundle/접근성 기준 적용 | | 아이콘 | 준비됨 | Lucide static vendor facade와 semantic icon/IconButton 접근성 계약 | 의미 icon 추가 시 bundle/접근성 기준 적용 |
| 폼 | 준비됨 | Zod 기반 local facade, error summary/focus, 422 allowlist, dirty/pending/conflict 정책 | 복합 form 요구가 생기면 VD-04 조건으로 vendor adapter 평가 | | 폼 | 준비됨 | Zod 기반 local facade, error summary/focus, 422 allowlist, dirty/pending/conflict 정책 | 복합 form 요구가 생기면 VD-04 조건으로 vendor adapter 평가 |
| 국제화 | 준비됨 | 137-key typed catalog, locale provider, Intl formatter, safe fallback/alias, pseudo·RTL gate | 실제 locale·번역 승인은 프로젝트에서 연결 | | 국제화 | 준비됨 | 137-key typed catalog, locale provider, Intl formatter, safe fallback/alias, pseudo·RTL gate | 실제 locale·번역 승인은 프로젝트에서 연결 |
| logging/diagnostics | 준비됨 | 별도 `DiagnosticsPort`, 8-event registry, allowlist, bounded/no-op adapter와 production producer | 실제 프로젝트의 remote sink는 port 뒤에서 선택 | | logging/diagnostics | 준비됨 | 별도 `DiagnosticsPort`, 8-event registry, allowlist, bounded/no-op adapter와 production producer | 실제 프로젝트의 remote sink는 port 뒤에서 선택 |
| telemetry | 준비됨/프로젝트 선택 | 5-event registry, bounded queue, redaction/value policy, boot·HTTP·render·release·drop producer | analytics/RUM/error vendor와 consent는 프로젝트에서 선택 | | telemetry | 준비됨/프로젝트 선택 | 5-event registry, bounded queue, redaction/value policy, boot·HTTP·render·release·drop producer | analytics/RUM/error vendor와 consent는 프로젝트에서 선택 |
| 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 | | 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 |
| 단위·통합·E2E | 준비됨 | Vitest, RTL, MSW, Playwright 3엔진 | TS 테스트 검사, 실제 bootstrap 통합, 위험 시나리오 보강 | | 단위·통합·E2E | 준비됨 | source/test strict typecheck, shared MSW 19개 scenario, 실제 bootstrap, built-dist 3엔진·compact E2E | 제품별 critical flow를 같은 catalog/gate에 추가 |
| UI 회귀 검증 | 미제공 | axe/reflow는 있으나 visual baseline 없음 | Storybook 또는 동급 workshop과 시각 회귀 | | UI 회귀 검증 | 준비됨 | dev-only Storybook interaction/axe와 pinned Chromium visual baseline 4종 | cloud review와 다중 OS/device는 프로젝트 선택 |
| 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 8단계 검증 | 새 contribution도 같은 제거 gate에 포함 | | 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 9단계 검증 | 새 contribution도 같은 제거 gate에 포함 |
| registry·compatibility 집행 | 부분 준비 | registry와 gate는 있으나 실제 before/after 및 orphan 검사가 제한적 | type/reference/orphan/diff/migration을 자동 검증 | | registry·compatibility 집행 | 준비됨 | 10개 registry type/reference/consumer/orphan, 승인 digest와 actual semantic diff, breaking evidence | public 계약 변경 시 baseline review 유지 |
| 공급망 검사 | 부분 준비 | lockfile·문서·gate는 있으나 실제 transitive 취약점/license/SBOM 깊이가 부족 | pinned scanner와 policy exception/증적 연결 | | 공급망 검사 | 부분 준비 | lockfile·문서·gate는 있으나 실제 transitive 취약점/license/SBOM 깊이가 부족 | pinned scanner와 policy exception/증적 연결 |
| realtime·offline·file 등 | 프로젝트 선택 | 현재 없음 | port/adapter recipe와 선택 기준 제공 | | realtime·offline·file 등 | 프로젝트 선택 | 현재 없음 | port/adapter recipe와 선택 기준 제공 |
docs/architecture/frontend-platform-implementation-roadmap.md
+29
View File
@@ -808,6 +808,35 @@ RP-10은 직전 승인 registry snapshot과 test evidence다. flaky visual/brows
infrastructure commit은 product behavior와 분리한다. 장기 skip으로 PASS하지 않고 infrastructure commit은 product behavior와 분리한다. 장기 skip으로 PASS하지 않고
owner와 만료 시한이 있는 quarantine만 허용한다. owner와 만료 시한이 있는 quarantine만 허용한다.
**구현 증거 (2026-07-26)**
- VD-08에서 dev-only Storybook static workshop과 production build를 대상으로 한
local Playwright visual baseline을 채택하고 cloud review는 선택 사항으로
분리했다.
- 10개 registry의 required field, runtime type, enum, unique, cross-reference,
consumer와 orphan을 검사하고 승인 snapshot digest와 현재 snapshot의 actual
semantic diff를 계산한다. 행·field·type·path뿐 아니라 registry 검증 계약
변경도 breaking evidence 대상이다.
- ordering-only 변경은 `none`, row addition은 `additive`, 일반 값 변경은
`behavior-change`, 제거/type/path/contract 변경은 `breaking`으로 계산한다.
breaking에는 version, migration, compatibility window, rollback과 owner를
요구하며 digest 변조와 누락 fixture가 실제로 실패한다.
- API operation별 19개 shared MSW scenario catalog와 strict unhandled-request
server를 제공하고 reference vertical integration이 공통 envelope/handler를
사용한다.
- 기본 Playwright는 `build` + `preview`의 실제 `dist`를 Chromium, Firefox,
WebKit에서 검사하고 별도 compact project를 제공한다. 개발 피드백용 Vite
profile은 `playwright.dev.config.js`로 분리했다.
- Storybook public primitive story, interaction과 axe test, wide/compact/
pseudo/dark/state surface의 pinned Chromium visual baseline 4종을 CI evidence로
연결했다.
- V8 coverage와 9개 high-risk module을 대상으로 40개 scoped threshold를
적용하고 threshold 미달 fixture를 차단한다.
- deterministic clock/random/scheduler/storage, unexpected console/page error/
request failure 정책, 무소유 skip과 full-screen mask 금지 gate를 제공한다.
- JUnit, HTML report, trace/screenshot, coverage, registry와 fixture artifact를
기존 26개 blocking gate taxonomy에 연결했다.
### 11. `feature-frontend-supply-chain-verification` ### 11. `feature-frontend-supply-chain-verification`
**목표** **목표**
docs/testing/frontend-platform-testing-strategy.md
+42 -53
View File
@@ -43,7 +43,12 @@
- `test:unit` - `test:unit`
- `test:component` - `test:component`
- `test:integration` - `test:integration`
- `test:coverage`
- `test:e2e` - `test:e2e`
- `test:e2e:dev`
- `build:storybook`
- `test:storybook`
- `test:visual`
- `test:a11y` - `test:a11y`
- `review:a11y-manual` - `review:a11y-manual`
- `test:sample-removal` - `test:sample-removal`
@@ -67,7 +72,7 @@ field/documentation 단계를 구성한다.
- 320px reflow와 mobile navigation을 E2E로 확인한다. - 320px reflow와 mobile navigation을 E2E로 확인한다.
- release build의 bundle과 lab performance budget이 별도 gate다. - release build의 bundle과 lab performance budget이 별도 gate다.
### 2.3 확인된 공백 ### 2.3 RP-10에서 닫힌 공백과 남은 외부 범위
#### 테스트 TypeScript typecheck 기반 #### 테스트 TypeScript typecheck 기반
@@ -76,20 +81,12 @@ field/documentation 단계를 구성한다.
검사하되 실패를 의도한 `tests/fixtures`는 별도 negative command가 소유한다. 검사하되 실패를 의도한 `tests/fixtures`는 별도 negative command가 소유한다.
Vitest의 변환 성공을 TypeScript typecheck의 대체물로 취급하지 않는다. Vitest의 변환 성공을 TypeScript typecheck의 대체물로 취급하지 않는다.
#### 실제 bootstrap integration test가 없다 #### 실제 bootstrap integration
`tests/component/bootstrap-shell.test.jsx`는 production bootstrap을 import하지 runtime config와 release manifest를 검증한 composition root에서 실제 provider
않고 테스트 내부의 `<TestShell>`만 렌더링한다. E2E는 실제 entry를 통과하지만, 순서와 application input을 연결하는 component/integration test를 제공한다.
다음 실패를 작은 통합 테스트에서 식별하기 어렵다. production Playwright profile은 source fixture가 아니라 `build` + `preview`의
실제 entry와 hashed route chunk를 사용한다.
- runtime config fetch 실패
- config/manifest mismatch
- adapter composition 실패
- provider 순서 또는 누락
- external auth owner 유무
- product tree를 마운트하기 전 fail-closed
- boot error shell의 safe metadata
- StrictMode와 unmount cleanup
#### TanStack Query의 React integration test 기반 #### TanStack Query의 React integration test 기반
@@ -100,53 +97,44 @@ optimistic commit/rollback, conflict 해제와 namespace invalidation이 실제
QueryClient 위에서 실행된다. HTTP 자동 retry가 소유자이므로 이 adapter의 QueryClient 위에서 실행된다. HTTP 자동 retry가 소유자이므로 이 adapter의
query/mutation vendor retry는 꺼져 있다. query/mutation vendor retry는 꺼져 있다.
#### Form 테스트가 단일 TextField 흐름에 머문다 #### Form과 route 위험
현재 component/E2E는 label, description, error association과 빈 값 submit을 form component/reference feature test가 error summary, 첫 오류 focus, Zod
검사한다. error summary, 첫 오류 focus, async validation race, 422 field error, transform, 422 allowlist, double submit, dirty navigation, optimistic rollback과
double submit, dirty navigation, mutation conflict는 없다. conflict를 검증한다. route registry/runtime 양방향 참조, codec, lazy module,
location reset, scroll restoration, blocker와 bounded chunk recovery도
unit/component/built artifact 검증에 연결됐다.
#### Route registry와 실행 tree가 별도로 테스트된다 #### Storybook과 시각 회귀
registry snapshot과 일부 navigation/access policy test는 있으나 다음 계약을 public design-system primitive를 실제 platform provider로 렌더하는 dev-only
강제하지 않는다. Storybook, interaction/axe test와 production build를 대상으로 한
`toHaveScreenshot()` baseline 4종을 제공한다. cloud review, 다중 OS font
rasterization과 실제 device farm은 프로젝트가 요구할 때 연결한다.
- 모든 route ID에 lazy runtime module이 존재하는가 #### Shared MSW와 결정성
- params/search가 실제 codec으로 검증되는가
- deep link와 basename refresh가 동작하는가
- chunk load failure가 1회 reload/support surface로 연결되는가
- route error boundary가 location 변경 시 reset되는가
- scroll restoration과 form navigation blocker가 동작하는가
#### Storybook과 시각 회귀가 없다 operation별 success/empty/slow/network/timeout/content/envelope/schema/auth/
403/404/409/422/429/retry/terminal을 포함한 19개 scenario catalog와 strict
unhandled-request server를 공유한다. clock/random/scheduler/storage helper와
browser console/page/network failure 정책으로 비결정적 우회를 차단한다.
`/examples/ui`는 통합 gallery지만 component별 모든 state를 격리하지 않는다. #### Built-dist와 compact E2E
Storybook story, interaction story, story-level axe, `toHaveScreenshot()` baseline이
없다. `screenshot: "only-on-failure"`는 디버깅 증거이며 시각 회귀 테스트가 아니다.
#### MSW scenario가 공유되지 않는다 기본 `test:e2e`는 CI에서 기존 server를 재사용하지 않고 `build` + `preview`를
Chromium, Firefox, WebKit과 compact project로 실행한다. 빠른 Vite 개발 profile은
`test:e2e:dev`로 분리한다.
integration file마다 `setupServer`, handler, response body를 다시 정의한다. #### 위험 기반 coverage
Node integration, Storybook browser, feature component test, E2E mock service가 같은
시나리오 이름과 contract fixture를 공유하지 않는다.
#### E2E가 개발 서버를 대상으로 한다 V8 text/JSON/LCOV를 생성하고 전체 기준과 retry/storage/telemetry/compatibility/
performance/promotion/chunk/diagnostics/registry compatibility 9개 high-risk
module에 40개 scoped threshold를 적용한다. critical module 누락 또는 threshold
미달 fixture는 merge gate를 실패시킨다.
현재 Playwright web server는 `pnpm dev`다. route behavior 확인에는 유효하지만 남은 범위는 실제 device/browser farm, cloud visual approval, 외부 인증·telemetry
다음 release 위험은 production build/preview에서만 확인할 수 있다. provider와 production field data다. 이 증거가 없을 때 저장소 내부 test를
`PRODUCTION_READY`의 대체물로 사용하지 않는다.
- hashed lazy chunk
- source 변환과 tree shaking
- base path
- deep-link fallback
- build-time environment
- release manifest와 runtime config 조합
- minified code의 chunk failure
#### Coverage가 실행·차단되지 않는다
`vitest.config.js`에는 reporter만 선언되어 있고 coverage provider, script,
threshold, diff policy가 없다.
## 3. 위험 기반 테스트 계층 ## 3. 위험 기반 테스트 계층
@@ -1228,8 +1216,9 @@ corepack pnpm build
corepack pnpm check:bundle corepack pnpm check:bundle
``` ```
TypeScript test, Storybook, coverage, visual, built-dist 명령이 도입되면 위 목록과 TypeScript test, Storybook, coverage, visual과 built-dist 명령은
CI registry에 추가한다. `config/ci/gates.json`의 blocking step과 JUnit/HTML/trace/fixture evidence에
연결되어 있다.
## 18. Feature Definition of Done ## 18. Feature Definition of Done
eslint.config.js
+6
View File
@@ -293,6 +293,12 @@ export default [
}, },
}, },
}, },
{
files: [`tests/support/browser/**/*.${sourceExtensions}`],
rules: {
"react-hooks/rules-of-hooks": "off",
},
},
{ {
files: [ files: [
`tests/fixtures/architecture/forbidden/**/*.${sourceExtensions}`, `tests/fixtures/architecture/forbidden/**/*.${sourceExtensions}`,
package.json
+18 -1
View File
@@ -13,7 +13,7 @@
"build": "vite build && node scripts/generate-build-manifest.mjs", "build": "vite build && node scripts/generate-build-manifest.mjs",
"build:release": "corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security", "build:release": "corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security",
"preview": "vite preview", "preview": "vite preview",
"lint": "eslint src scripts tests vite.config.js vitest.config.js playwright.config.js --max-warnings=0", "lint": "eslint src scripts tests .storybook vite.config.js vitest.config.js playwright*.config.js --max-warnings=0",
"check:architecture": "node scripts/check-architecture.mjs", "check:architecture": "node scripts/check-architecture.mjs",
"check:design-system": "node scripts/check-design-system.mjs", "check:design-system": "node scripts/check-design-system.mjs",
"check:design-system:fixture": "node scripts/check-design-system.mjs --fixture", "check:design-system:fixture": "node scripts/check-design-system.mjs --fixture",
@@ -42,16 +42,29 @@
"test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml", "test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml",
"test:integration": "vitest run tests/integration --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/integration.xml", "test:integration": "vitest run tests/integration --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/integration.xml",
"test:e2e": "playwright test", "test:e2e": "playwright test",
"test:e2e:dev": "playwright test --config playwright.dev.config.js",
"storybook": "storybook dev -p 6006",
"build:storybook": "storybook build -o artifacts/storybook/static",
"test:storybook": "playwright test --config playwright.storybook.config.js",
"test:visual": "playwright test --config playwright.visual.config.js",
"test:visual:update": "playwright test --config playwright.visual.config.js --update-snapshots",
"check:test-evidence": "node scripts/check-test-evidence.mjs",
"check:test-evidence:fixture": "node scripts/check-test-evidence.mjs --source-root tests/fixtures/test-evidence/forbidden --artifact artifacts/quality/test-evidence-fixture.json",
"test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.mjs", "test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.mjs",
"review:a11y-manual": "node scripts/verify-a11y-manual.mjs", "review:a11y-manual": "node scripts/verify-a11y-manual.mjs",
"test:sample-removal": "node scripts/test-sample-removal.mjs", "test:sample-removal": "node scripts/test-sample-removal.mjs",
"test:reference-feature": "vitest run tests/features/reference-feature --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/reference-feature.xml --passWithNoTests", "test:reference-feature": "vitest run tests/features/reference-feature --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/reference-feature.xml --passWithNoTests",
"test:coverage": "vitest run tests/runtime-schema tests/unit tests/component tests/integration tests/features/reference-feature --coverage --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/coverage.xml && node scripts/check-risk-coverage.mjs",
"check:coverage:fixture": "node scripts/check-risk-coverage.mjs --summary tests/fixtures/coverage/below-threshold.json --artifact artifacts/quality/risk-coverage-fixture.json",
"test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature", "test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature",
"verify:lockfile": "corepack pnpm install --frozen-lockfile", "verify:lockfile": "corepack pnpm install --frozen-lockfile",
"generate:supply-chain": "node scripts/generate-supply-chain.mjs", "generate:supply-chain": "node scripts/generate-supply-chain.mjs",
"scan:security": "node scripts/security-scan.mjs", "scan:security": "node scripts/security-scan.mjs",
"check:browser-security": "node scripts/check-browser-security.mjs", "check:browser-security": "node scripts/check-browser-security.mjs",
"check:registries": "node scripts/check-registries.mjs", "check:registries": "node scripts/check-registries.mjs",
"check:registries:structure": "node scripts/check-registries.mjs --no-baseline",
"check:registries:compatibility-fixtures": "node scripts/check-registry-compatibility-fixtures.mjs",
"check:registries:baseline-fixture": "node scripts/check-registries.mjs --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json", "check:registries:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
"check:routes:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json", "check:routes:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
"verify:compatibility": "node scripts/check-compatibility.mjs", "verify:compatibility": "node scripts/check-compatibility.mjs",
@@ -82,6 +95,8 @@
"@babel/plugin-syntax-typescript": "8.0.3", "@babel/plugin-syntax-typescript": "8.0.3",
"@eslint/js": "10.0.1", "@eslint/js": "10.0.1",
"@playwright/test": "1.62.0", "@playwright/test": "1.62.0",
"@storybook/addon-a11y": "10.5.4",
"@storybook/react-vite": "10.5.4",
"@tailwindcss/vite": "4.3.3", "@tailwindcss/vite": "4.3.3",
"@testing-library/jest-dom": "7.0.0", "@testing-library/jest-dom": "7.0.0",
"@testing-library/react": "16.3.2", "@testing-library/react": "16.3.2",
@@ -90,12 +105,14 @@
"@types/react": "19.2.8", "@types/react": "19.2.8",
"@types/react-dom": "19.2.3", "@types/react-dom": "19.2.3",
"@vitejs/plugin-react": "6.0.4", "@vitejs/plugin-react": "6.0.4",
"@vitest/coverage-v8": "4.1.10",
"dependency-cruiser": "18.1.0", "dependency-cruiser": "18.1.0",
"eslint": "10.8.0", "eslint": "10.8.0",
"eslint-plugin-react-hooks": "7.1.1", "eslint-plugin-react-hooks": "7.1.1",
"globals": "17.7.0", "globals": "17.7.0",
"jsdom": "29.1.1", "jsdom": "29.1.1",
"msw": "2.15.0", "msw": "2.15.0",
"storybook": "10.5.4",
"tailwindcss": "4.3.3", "tailwindcss": "4.3.3",
"typescript": "7.0.2", "typescript": "7.0.2",
"vite": "8.1.5", "vite": "8.1.5",
playwright.config.js
+31 -7
View File
@@ -6,20 +6,44 @@ export default defineConfig({
reporter: [ reporter: [
["list"], ["list"],
["html", { outputFolder: "./artifacts/tests/e2e/report", open: "never" }], ["html", { outputFolder: "./artifacts/tests/e2e/report", open: "never" }],
["junit", { outputFile: "./artifacts/tests/e2e/results.xml" }],
], ],
use: { use: {
baseURL: "http://127.0.0.1:5173", baseURL: "http://127.0.0.1:4173",
trace: "retain-on-failure", trace: "retain-on-failure",
screenshot: "only-on-failure", screenshot: "only-on-failure",
}, },
webServer: { webServer: {
command: "corepack pnpm dev --host 127.0.0.1", command:
url: "http://127.0.0.1:5173", "corepack pnpm build && corepack pnpm preview --host 127.0.0.1 --port 4173",
reuseExistingServer: !process.env.CI, url: "http://127.0.0.1:4173",
reuseExistingServer: false,
}, },
projects: [ projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } }, {
{ name: "firefox", use: { ...devices["Desktop Firefox"] } }, name: "chromium",
{ name: "webkit", use: { ...devices["Desktop Safari"] } }, testIgnore: "**/compact-smoke.spec.js",
use: { ...devices["Desktop Chrome"] },
},
{
name: "firefox",
testIgnore: "**/compact-smoke.spec.js",
use: { ...devices["Desktop Firefox"] },
},
{
name: "webkit",
testIgnore: "**/compact-smoke.spec.js",
use: { ...devices["Desktop Safari"] },
},
{
name: "chromium-compact",
testMatch: "**/compact-smoke.spec.js",
use: {
...devices["Desktop Chrome"],
viewport: { width: 390, height: 844 },
hasTouch: true,
isMobile: true,
},
},
], ],
}); });
playwright.dev.config.js
+16
View File
@@ -0,0 +1,16 @@
import { defineConfig } from "@playwright/test";
import releaseConfig from "./playwright.config.js";
export default defineConfig({
...releaseConfig,
use: {
...releaseConfig.use,
baseURL: "http://127.0.0.1:5173",
},
webServer: {
command: "corepack pnpm dev --host 127.0.0.1",
url: "http://127.0.0.1:5173",
reuseExistingServer: true,
},
});
playwright.storybook.config.js
+34
View File
@@ -0,0 +1,34 @@
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/storybook",
outputDir: "./artifacts/tests/storybook/results",
reporter: [
["list"],
[
"html",
{
outputFolder: "./artifacts/tests/storybook/report",
open: "never",
},
],
[
"junit",
{ outputFile: "./artifacts/tests/storybook/results.xml" },
],
],
use: {
baseURL: "http://127.0.0.1:6006",
trace: "retain-on-failure",
screenshot: "only-on-failure",
},
webServer: {
command:
"corepack pnpm build:storybook && node scripts/serve-static.mjs artifacts/storybook/static 6006",
url: "http://127.0.0.1:6006",
reuseExistingServer: false,
},
projects: [
{ name: "chromium-workshop", use: { ...devices["Desktop Chrome"] } },
],
});
playwright.visual.config.js
+37
View File
@@ -0,0 +1,37 @@
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/visual",
snapshotDir: "./tests/visual/__snapshots__",
outputDir: "./artifacts/tests/visual/results",
reporter: [
["list"],
[
"html",
{ outputFolder: "./artifacts/tests/visual/report", open: "never" },
],
["junit", { outputFile: "./artifacts/tests/visual/results.xml" }],
],
expect: {
toHaveScreenshot: {
animations: "disabled",
caret: "hide",
maxDiffPixelRatio: 0.002,
scale: "css",
},
},
use: {
...devices["Desktop Chrome"],
baseURL: "http://127.0.0.1:4174",
colorScheme: "light",
locale: "en-US",
trace: "retain-on-failure",
},
webServer: {
command:
"corepack pnpm build && corepack pnpm preview --host 127.0.0.1 --port 4174",
url: "http://127.0.0.1:4174",
reuseExistingServer: false,
},
projects: [{ name: "chromium-visual" }],
});
pnpm-lock.yaml
Generated
+1470 -16
View File
File diff suppressed because it is too large Load Diff
pnpm-workspace.yaml
+1
View File
@@ -1,4 +1,5 @@
allowBuilds: allowBuilds:
esbuild: true
msw: true msw: true
minimumReleaseAgeExclude: minimumReleaseAgeExclude:
- '@playwright/test@1.62.0' - '@playwright/test@1.62.0'
schemas/artifacts/registry-snapshot.schema.json
+32 -7
View File
@@ -4,24 +4,49 @@
"required": [ "required": [
"schemaVersion", "schemaVersion",
"generatedAt", "generatedAt",
"compatibilityImpact", "baselineDigest",
"currentDigest",
"compatibility",
"failures", "failures",
"registries" "registries"
], ],
"properties": { "properties": {
"schemaVersion": { "const": 1 }, "schemaVersion": { "const": 2 },
"generatedAt": { "type": "string", "format": "date-time" }, "generatedAt": { "type": "string", "format": "date-time" },
"compatibilityImpact": { "baselineDigest": {
"enum": ["none", "additive", "behavior-change", "breaking"] "type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"currentDigest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"compatibility": {
"type": "object",
"required": ["impact", "changes"],
"properties": {
"impact": {
"enum": ["none", "additive", "behavior-change", "breaking"]
},
"changes": { "type": "array" }
},
"additionalProperties": false
}, },
"failures": { "type": "array", "maxItems": 0 }, "failures": { "type": "array", "maxItems": 0 },
"registries": { "registries": {
"type": "array", "type": "array",
"minItems": 8, "minItems": 10,
"maxItems": 8, "maxItems": 10,
"items": { "items": {
"type": "object", "type": "object",
"required": ["registryId", "owner", "source", "rowCount", "rows"] "required": [
"registryId",
"owner",
"source",
"rowCount",
"contract",
"rows"
]
} }
} }
}, },
scripts/check-registries.mjs
+243 -56
View File
@@ -1,28 +1,65 @@
import { access, mkdir, readFile, writeFile } from "node:fs/promises"; import {
access,
mkdir,
readFile,
readdir,
writeFile,
} from "node:fs/promises";
import path from "node:path"; import path from "node:path";
import { pathToFileURL } from "node:url"; import { pathToFileURL } from "node:url";
/** @param {string} name @param {string} fallback */ import {
canonicalizeRegistryValue,
diffRegistrySnapshots,
registrySnapshotDigest,
validateBreakingEvidence,
verifyRegistryBaselineApproval,
} from "./lib/registry-compatibility.mjs";
/** @param {string} name @param {string | undefined} fallback */
function argumentValue(name, fallback) { function argumentValue(name, fallback) {
const index = process.argv.indexOf(name); const index = process.argv.indexOf(name);
return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback; return index >= 0 && process.argv[index + 1]
? process.argv[index + 1]
: fallback;
} }
const governancePath = argumentValue( const defaultGovernancePath = "config/contracts/registry-governance.json";
"--governance", const governancePath =
"config/contracts/registry-governance.json", /** @type {string} */ (
argumentValue("--governance", defaultGovernancePath)
);
const artifactPath =
/** @type {string} */ (
argumentValue("--artifact", "artifacts/quality/registries.json")
);
const usesRepositoryBaseline =
governancePath === defaultGovernancePath &&
!process.argv.includes("--no-baseline");
const baselinePath = argumentValue(
"--baseline",
usesRepositoryBaseline
? "config/contracts/registry-baseline.json"
: undefined,
); );
const artifactPath = argumentValue( const approvalPath = argumentValue(
"--artifact", "--approval",
"artifacts/quality/registries.json", usesRepositoryBaseline
? "config/contracts/registry-baseline.approval.json"
: undefined,
); );
const governance = JSON.parse( const evidencePath = argumentValue(
await readFile(governancePath, "utf8"), "--compatibility-evidence",
usesRepositoryBaseline
? "config/contracts/registry-change-evidence.json"
: undefined,
); );
const governance = JSON.parse(await readFile(governancePath, "utf8"));
const failures = []; const failures = [];
const owners = new Map(); const owners = new Map();
const snapshots = []; const snapshots = [];
const rowsByRegistry = new Map(); const rowsByRegistry = new Map();
const sourcesByRegistry = new Map();
const registryExtensions = [".js", ".jsx", ".mjs", ".ts", ".tsx", ".mts"]; const registryExtensions = [".js", ".jsx", ".mjs", ".ts", ".tsx", ".mts"];
/** @param {string} declaredPath */ /** @param {string} declaredPath */
@@ -38,7 +75,7 @@ async function resolveRegistrySource(declaredPath) {
await access(candidate); await access(candidate);
candidates.push(candidate); candidates.push(candidate);
} catch { } catch {
// A migration may legitimately replace the declared extension. // A TypeScript migration may replace the declared extension.
} }
} }
if (candidates.length > 1) { if (candidates.length > 1) {
@@ -50,6 +87,44 @@ async function resolveRegistrySource(declaredPath) {
return candidates[0] ?? null; return candidates[0] ?? null;
} }
/** @param {unknown} value */
function runtimeType(value) {
if (value === null) return "null";
if (Array.isArray(value)) return "array";
if (Number.isInteger(value)) return "integer";
return typeof value;
}
/** @param {unknown} value @param {string} declaration */
function matchesDeclaredType(value, declaration) {
const actual = runtimeType(value);
return declaration
.split("|")
.some(
(candidate) =>
candidate === actual ||
(candidate === "number" && actual === "integer"),
);
}
/** @param {string} directory @returns {Promise<string[]>} */
async function filesBelow(directory) {
try {
const entries = await readdir(directory, { withFileTypes: true });
const groups = await Promise.all(
entries.map((entry) => {
const target = path.join(directory, entry.name);
return entry.isDirectory() ? filesBelow(target) : [target];
}),
);
return groups.flat().filter((file) =>
/\.(?:js|jsx|mjs|ts|tsx|mts)$/.test(file),
);
} catch {
return [];
}
}
for (const specification of governance.registries) { for (const specification of governance.registries) {
if (owners.has(specification.registryId)) { if (owners.has(specification.registryId)) {
failures.push(`duplicate owner for ${specification.registryId}`); failures.push(`duplicate owner for ${specification.registryId}`);
@@ -74,6 +149,10 @@ for (const specification of governance.registries) {
} }
rowsByRegistry.set(specification.registryId, rows); rowsByRegistry.set(specification.registryId, rows);
sourcesByRegistry.set(
specification.registryId,
sourcePath ?? specification.path,
);
for (const [rowName, row] of Object.entries(rows)) { for (const [rowName, row] of Object.entries(rows)) {
if (!row || typeof row !== "object" || Array.isArray(row)) { if (!row || typeof row !== "object" || Array.isArray(row)) {
@@ -85,6 +164,26 @@ for (const specification of governance.registries) {
failures.push(`${specification.registryId}.${rowName} missing ${field}`); failures.push(`${specification.registryId}.${rowName} missing ${field}`);
} }
} }
for (const [field, declaredType] of Object.entries(
specification.fieldTypes ?? {},
)) {
if (
field in row &&
!matchesDeclaredType(row[field], String(declaredType))
) {
failures.push(
`${specification.registryId}.${rowName}.${field} expected ${declaredType}, received ${runtimeType(row[field])}`,
);
}
}
if (
specification.keyField &&
row[specification.keyField] !== rowName
) {
failures.push(
`${specification.registryId}.${rowName}.${specification.keyField} must match its registry key`,
);
}
} }
for (const field of specification.uniqueFields ?? []) { for (const field of specification.uniqueFields ?? []) {
@@ -93,12 +192,13 @@ for (const specification of governance.registries) {
if (!row || typeof row !== "object" || Array.isArray(row)) continue; if (!row || typeof row !== "object" || Array.isArray(row)) continue;
const value = row[field]; const value = row[field];
if (value === undefined) continue; if (value === undefined) continue;
if (values.has(value)) { const identity = JSON.stringify(canonicalizeRegistryValue(value));
if (values.has(identity)) {
failures.push( failures.push(
`${specification.registryId}.${rowName} duplicates ${field}=${String(value)} from ${values.get(value)}`, `${specification.registryId}.${rowName} duplicates ${field}=${String(value)} from ${values.get(identity)}`,
); );
} else { } else {
values.set(value, rowName); values.set(identity, rowName);
} }
} }
} }
@@ -121,12 +221,22 @@ for (const specification of governance.registries) {
} }
} }
const contract = Object.freeze({
requiredFields: specification.requiredFields,
fieldTypes: specification.fieldTypes ?? {},
uniqueFields: specification.uniqueFields ?? [],
allowedValues: specification.allowedValues ?? {},
references: specification.references ?? [],
keyField: specification.keyField ?? null,
breakingFields: specification.breakingFields ?? [],
});
snapshots.push({ snapshots.push({
registryId: specification.registryId, registryId: specification.registryId,
owner: specification.owner, owner: specification.owner,
source: sourcePath ?? specification.path, source: sourcePath ?? specification.path,
rowCount: Object.keys(rows).length, rowCount: Object.keys(rows).length,
rows, contract,
rows: canonicalizeRegistryValue(rows),
}); });
} }
@@ -145,18 +255,74 @@ for (const specification of governance.registries) {
Object.values(targetRows) Object.values(targetRows)
.filter((row) => row && typeof row === "object" && !Array.isArray(row)) .filter((row) => row && typeof row === "object" && !Array.isArray(row))
.map((row) => row[reference.targetField]) .map((row) => row[reference.targetField])
.filter((value) => value !== undefined), .filter((value) => value !== undefined && value !== null),
); );
for (const [rowName, row] of Object.entries(rows)) { for (const [rowName, row] of Object.entries(rows)) {
if (!row || typeof row !== "object" || Array.isArray(row)) continue; if (!row || typeof row !== "object" || Array.isArray(row)) continue;
const value = row[reference.field]; const value = row[reference.field];
if (value !== undefined && !targetValues.has(value)) { if (
value !== undefined &&
value !== null &&
!targetValues.has(value)
) {
failures.push( failures.push(
`${specification.registryId}.${rowName}.${reference.field} references unknown ${reference.registryId}.${reference.targetField}=${String(value)}`, `${specification.registryId}.${rowName}.${reference.field} references unknown ${reference.registryId}.${reference.targetField}=${String(value)}`,
); );
} }
} }
} }
for (const consumer of specification.consumers ?? []) {
try {
const source = await readFile(consumer.path, "utf8");
if (!source.includes(consumer.token)) {
failures.push(
`${specification.registryId} consumer ${consumer.path} is missing ${consumer.token}`,
);
}
} catch {
failures.push(
`${specification.registryId} consumer source is missing: ${consumer.path}`,
);
}
}
if (specification.consumerIdentityField) {
const consumerFiles = (
await Promise.all(
(specification.consumerDirectories ?? []).map(filesBelow),
)
).flat();
const sourcePath = sourcesByRegistry.get(specification.registryId);
const consumerText = (
await Promise.all(
consumerFiles
.filter((file) => file !== sourcePath)
.map((file) => readFile(file, "utf8")),
)
).join("\n");
const exemptions = new Set(specification.orphanExemptRows ?? []);
for (const [rowName, row] of Object.entries(rows)) {
if (
!row ||
typeof row !== "object" ||
Array.isArray(row) ||
exemptions.has(rowName)
) {
continue;
}
const identity = row[specification.consumerIdentityField];
if (
(typeof identity !== "string" &&
typeof identity !== "number") ||
!consumerText.includes(String(identity))
) {
failures.push(
`${specification.registryId}.${rowName} has no executable consumer for ${specification.consumerIdentityField}=${String(identity)}`,
);
}
}
}
} }
const sourceFiles = governance.sourceDirectories ?? [ const sourceFiles = governance.sourceDirectories ?? [
@@ -166,59 +332,80 @@ const sourceFiles = governance.sourceDirectories ?? [
]; ];
const adHocPatterns = [ const adHocPatterns = [
{ name: "direct fetch", expression: /\bfetch\s*\(/ }, { name: "direct fetch", expression: /\bfetch\s*\(/ },
{ name: "direct localStorage", expression: /\blocalStorage\.(?:get|set|remove)Item/ }, {
name: "direct localStorage",
expression: /\blocalStorage\.(?:get|set|remove)Item/,
},
{ name: "direct import.meta.env", expression: /\bimport\.meta\.env\./ }, { name: "direct import.meta.env", expression: /\bimport\.meta\.env\./ },
{ name: "raw API path", expression: /["']\/api\// }, { name: "raw API path", expression: /["']\/api\// },
]; ];
/** @param {string} directory */ for (const sourceDirectory of sourceFiles) {
async function scanDirectory(directory) { for (const file of await filesBelow(sourceDirectory)) {
try { const content = await readFile(file, "utf8");
await access(directory);
} catch {
return;
}
const entries = await import("node:fs/promises").then(({ readdir }) =>
readdir(directory, { withFileTypes: true }),
);
for (const entry of entries) {
const target = path.join(directory, entry.name);
if (entry.isDirectory()) {
await scanDirectory(target);
continue;
}
if (!/\.(js|jsx|mjs|ts|tsx|mts)$/.test(entry.name)) continue;
const content = await readFile(target, "utf8");
for (const pattern of adHocPatterns) { for (const pattern of adHocPatterns) {
if (pattern.expression.test(content)) { if (pattern.expression.test(content)) {
failures.push(`ad-hoc ${pattern.name} in ${target}`); failures.push(`ad-hoc ${pattern.name} in ${file}`);
} }
} }
} }
} }
for (const sourceDirectory of sourceFiles) { const currentSnapshot =
await scanDirectory(sourceDirectory); /** @type {Readonly<Record<string, unknown>>} */ (
canonicalizeRegistryValue({
schemaVersion: 2,
registries: snapshots,
})
);
let baselineDigest = null;
let currentDigest = registrySnapshotDigest(currentSnapshot);
let compatibility =
/** @type {{impact: string, changes: readonly Record<string, unknown>[]}} */ ({
impact: "not-evaluated",
changes: [],
});
if (baselinePath && approvalPath && evidencePath) {
try {
const baseline = JSON.parse(await readFile(baselinePath, "utf8"));
const approval = JSON.parse(await readFile(approvalPath, "utf8"));
const approvalResult = verifyRegistryBaselineApproval(baseline, approval);
baselineDigest = approvalResult.actualDigest;
if (!approvalResult.passed) {
failures.push(
`registry baseline approval digest mismatch: approved=${approvalResult.approvedDigest} actual=${approvalResult.actualDigest}`,
);
}
compatibility = diffRegistrySnapshots(baseline, currentSnapshot);
const evidence = JSON.parse(await readFile(evidencePath, "utf8"));
const evidenceResult = validateBreakingEvidence(compatibility, evidence);
failures.push(...evidenceResult.failures);
} catch (error) {
failures.push(
`registry compatibility evidence unavailable: ${
error instanceof Error ? error.name : "unknown"
}`,
);
}
} }
await mkdir("artifacts/quality", { recursive: true }); const report = {
await writeFile( schemaVersion: 2,
artifactPath, generatedAt: new Date().toISOString(),
`${JSON.stringify( baselineDigest,
{ currentDigest,
schemaVersion: 1, compatibility,
generatedAt: new Date().toISOString(), failures,
compatibilityImpact: governance.compatibilityImpact.current, registries: snapshots,
failures, };
registries: snapshots, await mkdir(path.dirname(artifactPath), { recursive: true });
}, await writeFile(artifactPath, `${JSON.stringify(report, null, 2)}\n`);
null,
2,
)}\n`,
);
if (failures.length > 0) { if (failures.length > 0) {
process.stderr.write(`Registry governance failed:\n${failures.join("\n")}\n`); process.stderr.write(`Registry governance failed:\n${failures.join("\n")}\n`);
process.exit(1); process.exit(1);
} }
process.stdout.write(`Registry governance: ${snapshots.length} registries PASS\n`); process.stdout.write(
`Registry governance: ${snapshots.length} registries PASS; compatibility=${compatibility.impact}\n`,
);
scripts/check-registry-compatibility-fixtures.mjs
+63
View File
@@ -0,0 +1,63 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import {
diffRegistrySnapshots,
validateBreakingEvidence,
verifyRegistryBaselineApproval,
} from "./lib/registry-compatibility.mjs";
const fixtures = JSON.parse(
await readFile(
"tests/fixtures/registry/compatibility/semantic-diff.json",
"utf8",
),
);
const results = [];
for (const fixture of fixtures.cases) {
const actual = diffRegistrySnapshots(fixture.before, fixture.after);
results.push({
id: fixture.id,
expected: fixture.expected,
actual: actual.impact,
passed: actual.impact === fixture.expected,
});
}
const breaking = diffRegistrySnapshots(
fixtures.breakingEvidence.before,
fixtures.breakingEvidence.after,
);
const missingEvidence = validateBreakingEvidence(breaking, {
schemaVersion: 1,
changes: [],
});
results.push({
id: "breaking-evidence-required",
expected: false,
actual: missingEvidence.passed,
passed: !missingEvidence.passed,
});
const tamperedApproval = verifyRegistryBaselineApproval(
fixtures.tamperedApproval.snapshot,
fixtures.tamperedApproval.approval,
);
results.push({
id: "tampered-baseline-digest",
expected: false,
actual: tamperedApproval.passed,
passed: !tamperedApproval.passed,
});
await mkdir("artifacts/quality", { recursive: true });
await writeFile(
"artifacts/quality/registry-compatibility-fixtures.json",
`${JSON.stringify({ schemaVersion: 1, results }, null, 2)}\n`,
);
if (results.some((result) => !result.passed)) {
process.stderr.write("Registry compatibility fixture failed.\n");
process.exit(1);
}
process.stdout.write(
`Registry compatibility fixtures: ${results.length} PASS\n`,
);
scripts/check-risk-coverage.mjs
+88
View File
@@ -0,0 +1,88 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";
/** @param {string} name @param {string} fallback */
function argumentValue(name, fallback) {
const index = process.argv.indexOf(name);
return index >= 0 && process.argv[index + 1]
? process.argv[index + 1]
: fallback;
}
const policyPath = argumentValue(
"--policy",
"config/testing/risk-coverage.json",
);
const summaryPath = argumentValue(
"--summary",
"artifacts/tests/coverage/coverage-summary.json",
);
const artifactPath = argumentValue(
"--artifact",
"artifacts/quality/risk-coverage.json",
);
const policy = JSON.parse(await readFile(policyPath, "utf8"));
const summary = JSON.parse(await readFile(summaryPath, "utf8"));
const failures = [];
/** @type {Array<{
* scope: string,
* metric: string,
* threshold: number,
* received: number | undefined,
* passed: boolean
* }>} */
const results = [];
/**
* @param {string} scope
* @param {Record<string, {pct: number}>} actual
* @param {Record<string, number>} minimum
*/
function evaluate(scope, actual, minimum) {
for (const [metric, threshold] of Object.entries(minimum)) {
const received = actual?.[metric]?.pct;
const passed =
typeof received === "number" &&
Number.isFinite(received) &&
received >= threshold;
results.push({ scope, metric, threshold, received, passed });
if (!passed) {
failures.push(
`${scope}.${metric} expected >= ${threshold}, received ${String(received)}`,
);
}
}
}
evaluate("total", summary.total, policy.summary);
for (const modulePolicy of policy.criticalModules) {
const key = Object.keys(summary).find(
(candidate) =>
candidate !== "total" &&
candidate.replaceAll("\\", "/").endsWith(`/${modulePolicy.path}`),
);
if (!key) {
failures.push(`critical module missing from coverage: ${modulePolicy.path}`);
continue;
}
evaluate(modulePolicy.path, summary[key], modulePolicy.minimum);
}
const artifact = {
schemaVersion: 1,
policy: policyPath,
summary: summaryPath,
status: failures.length === 0 ? "PASS" : "FAIL",
results,
failures,
};
await mkdir(path.dirname(artifactPath), { recursive: true });
await writeFile(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`);
if (failures.length > 0) {
process.stderr.write(`Risk coverage failed:\n- ${failures.join("\n- ")}\n`);
process.exit(1);
}
process.stdout.write(
`Risk coverage: PASS (${results.length} scoped thresholds)\n`,
);
scripts/check-test-evidence.mjs
+167
View File
@@ -0,0 +1,167 @@
import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import path from "node:path";
/** @param {string} name @param {string} fallback */
function argumentValue(name, fallback) {
const index = process.argv.indexOf(name);
return index >= 0 && process.argv[index + 1]
? process.argv[index + 1]
: fallback;
}
const sourceRoot = argumentValue("--source-root", "tests");
const artifactPath = argumentValue(
"--artifact",
"artifacts/quality/test-evidence.json",
);
const fixtureMode = sourceRoot !== "tests";
const failures = [];
const facts = {
scannedFiles: 0,
visualBaselines: 0,
sharedScenarios: 0,
};
/** @param {string} target @returns {Promise<string[]>} */
async function filesBelow(target) {
try {
const metadata = await stat(target);
if (metadata.isFile()) return [target];
const entries = await readdir(target, { withFileTypes: true });
const groups = await Promise.all(
entries.map((entry) => filesBelow(path.join(target, entry.name))),
);
return groups.flat();
} catch {
return [];
}
}
const sourceFiles = (await filesBelow(sourceRoot)).filter(
(file) => fixtureMode || !file.split(path.sep).includes("fixtures"),
);
for (const file of sourceFiles) {
if (!/\.(?:js|jsx|mjs|ts|tsx|fixture|txt)$/.test(file)) continue;
const source = await readFile(file, "utf8");
facts.scannedFiles += 1;
const skipPattern =
/\b(?:test|it|describe)(?:\.describe)?\.(?:skip|fixme)\s*\(/g;
if (skipPattern.test(source)) {
const quarantine =
/quarantine\(owner=[^)]+,\s*defect=[^)]+,\s*expires=\d{4}-\d{2}-\d{2}\)/;
if (!quarantine.test(source)) {
failures.push(`${file}: skip/fixme lacks owned expiring quarantine`);
}
}
const wholeUiMask =
/\bmask\s*:\s*\[[\s\S]{0,240}(?:locator|getByRole)\s*\(\s*["'](?:html|body|main|application|document)["']/i;
if (wholeUiMask.test(source)) {
failures.push(`${file}: screenshot mask may not cover the whole UI`);
}
}
if (!fixtureMode) {
const e2eConfig = await readFile("playwright.config.js", "utf8");
for (const token of [
"pnpm build",
"pnpm preview",
"reuseExistingServer: false",
'"junit"',
'trace: "retain-on-failure"',
'"chromium-compact"',
'"firefox"',
'"webkit"',
]) {
if (!e2eConfig.includes(token)) {
failures.push(`playwright.config.js missing release evidence token ${token}`);
}
}
const e2eFiles = (await filesBelow("tests/e2e")).filter((file) =>
/\.spec\.(?:js|ts)$/.test(file),
);
for (const file of e2eFiles) {
const source = await readFile(file, "utf8");
if (!source.includes("support/browser/strict-browser-test")) {
failures.push(`${file}: bypasses strict browser fixture`);
}
}
const scenarioCatalog = await readFile(
"tests/mocks/scenarios/catalog.ts",
"utf8",
);
const scenarioIdBlock =
scenarioCatalog.match(
/HTTP_SCENARIO_IDS\s*=\s*Object\.freeze\(\[([\s\S]*?)\]\s*as const\)/,
)?.[1] ?? "";
facts.sharedScenarios = (scenarioIdBlock.match(/"[^"]+"/g) ?? []).length;
if (facts.sharedScenarios < 19) {
failures.push("shared MSW catalog must retain all 19 failure scenarios");
}
const handler = await readFile(
"tests/mocks/handlers/reference-resources.ts",
"utf8",
);
if (
!handler.includes("assertOperationScenario") ||
!handler.includes("../scenarios/catalog.js")
) {
failures.push("MSW handler bypasses shared scenario catalog");
}
const baselineFiles = (await filesBelow("tests/visual/__snapshots__")).filter(
(file) => file.endsWith(".png"),
);
facts.visualBaselines = baselineFiles.length;
if (facts.visualBaselines < 4) {
failures.push("visual baseline requires at least four risk surfaces");
}
for (const required of [
"playwright.storybook.config.js",
"playwright.visual.config.js",
"tests/storybook/workshop.spec.ts",
"artifacts/tests/storybook/results.xml",
"artifacts/tests/visual/results.xml",
]) {
if ((await filesBelow(required)).length === 0) {
failures.push(`test evidence missing ${required}`);
}
}
const requiredBuiltFiles = [
"dist/index.html",
"dist/config.json",
"dist/release-manifest.json",
"dist/runtime-config.schema.json",
"dist/.vite/manifest.json",
];
for (const required of requiredBuiltFiles) {
if ((await filesBelow(required)).length === 0) {
failures.push(`built-dist contract missing ${required}`);
}
}
const sourceMaps = (await filesBelow("dist")).filter((file) =>
file.endsWith(".map"),
);
if (sourceMaps.length > 0) {
failures.push(`production dist contains source maps: ${sourceMaps.join(", ")}`);
}
}
const report = {
schemaVersion: 1,
sourceRoot,
status: failures.length === 0 ? "PASS" : "FAIL",
facts,
failures,
};
await mkdir(path.dirname(artifactPath), { recursive: true });
await writeFile(artifactPath, `${JSON.stringify(report, null, 2)}\n`);
if (failures.length > 0) {
process.stderr.write(`Test evidence failed:\n- ${failures.join("\n- ")}\n`);
process.exit(1);
}
process.stdout.write(
`Test evidence: PASS (${facts.scannedFiles} files, ${facts.visualBaselines} baselines, ${facts.sharedScenarios} scenarios)\n`,
);
scripts/lib/registry-compatibility.mjs
+321
View File
@@ -0,0 +1,321 @@
import { createHash } from "node:crypto";
export const COMPATIBILITY_IMPACTS = Object.freeze([
"none",
"additive",
"behavior-change",
"breaking",
]);
const impactRank = new Map(
COMPATIBILITY_IMPACTS.map((impact, index) => [impact, index]),
);
/** @param {unknown} value @returns {unknown} */
export function canonicalizeRegistryValue(value) {
if (Array.isArray(value)) {
const projected =
/** @type {unknown[]} */ (value.map(canonicalizeRegistryValue));
return projected.every(
(item) =>
item === null ||
["string", "number", "boolean"].includes(typeof item),
)
? projected.sort((left, right) =>
JSON.stringify(left).localeCompare(JSON.stringify(right)),
)
: projected;
}
if (value && typeof value === "object") {
return Object.fromEntries(
Object.entries(value)
.sort(([left], [right]) => left.localeCompare(right))
.map(([key, item]) => [key, canonicalizeRegistryValue(item)]),
);
}
return value;
}
/** @param {unknown} value @returns {string} */
export function canonicalRegistryJson(value) {
return JSON.stringify(canonicalizeRegistryValue(value)) ?? "undefined";
}
/** @param {unknown} snapshot */
export function registrySnapshotDigest(snapshot) {
return createHash("sha256")
.update(canonicalRegistryJson(snapshot))
.digest("hex");
}
/** @param {string} current @param {string} candidate */
function strongestImpact(current, candidate) {
return (impactRank.get(candidate) ?? 0) > (impactRank.get(current) ?? 0)
? candidate
: current;
}
/** @param {unknown} value */
function valueType(value) {
if (value === null) return "null";
if (Array.isArray(value)) return "array";
return typeof value;
}
/**
* @param {string} registryId
* @param {string} rowName
* @param {string} field
* @param {string} kind
*/
function changeId(registryId, rowName, field, kind) {
return `${registryId}:${rowName}:${field}:${kind}`;
}
/**
* Calculates a semantic diff. Object key and primitive-array ordering is
* canonicalized before comparison and therefore cannot create a false change.
*
* @param {Readonly<Record<string, unknown>>} before
* @param {Readonly<Record<string, unknown>>} after
*/
export function diffRegistrySnapshots(before, after) {
const changes = /** @type {Array<Record<string, unknown>>} */ ([]);
let impact = "none";
const beforeRegistries =
/** @type {Map<string, Record<string, unknown>>} */ (new Map(
/** @type {Array<Record<string, unknown>>} */ (before.registries ?? []).map(
(registry) => [String(registry.registryId), registry],
),
));
const afterRegistries =
/** @type {Map<string, Record<string, unknown>>} */ (new Map(
/** @type {Array<Record<string, unknown>>} */ (after.registries ?? []).map(
(registry) => [String(registry.registryId), registry],
),
));
const registryIds = new Set([
...beforeRegistries.keys(),
...afterRegistries.keys(),
]);
for (const registryId of [...registryIds].sort()) {
const previous = beforeRegistries.get(registryId);
const current = afterRegistries.get(registryId);
if (!previous || !current) {
const changeImpact = previous ? "breaking" : "additive";
impact = strongestImpact(impact, changeImpact);
changes.push({
changeId: changeId(registryId, "*", "*", previous ? "removed" : "added"),
registryId,
rowName: "*",
field: "*",
kind: previous ? "registry-removed" : "registry-added",
impact: changeImpact,
});
continue;
}
const previousContract =
/** @type {Record<string, unknown>} */ (previous.contract ?? {});
const currentContract =
/** @type {Record<string, unknown>} */ (current.contract ?? {});
const contractFields = new Set([
...Object.keys(previousContract),
...Object.keys(currentContract),
]);
for (const field of [...contractFields].sort()) {
const beforeHas = Object.hasOwn(previousContract, field);
const afterHas = Object.hasOwn(currentContract, field);
const beforeValue = previousContract[field];
const afterValue = currentContract[field];
if (
beforeHas &&
afterHas &&
canonicalRegistryJson(beforeValue) ===
canonicalRegistryJson(afterValue)
) {
continue;
}
const kind = !beforeHas
? "contract-field-added"
: !afterHas
? "contract-field-removed"
: "contract-field-changed";
impact = strongestImpact(impact, "breaking");
changes.push({
changeId: changeId(registryId, "$contract", field, kind),
registryId,
rowName: "$contract",
field,
kind,
impact: "breaking",
before: canonicalizeRegistryValue(beforeValue),
after: canonicalizeRegistryValue(afterValue),
});
}
const breakingFields = new Set(
/** @type {string[]} */ (
currentContract.breakingFields ?? []
),
);
const beforeRows =
/** @type {Record<string, Record<string, unknown>>} */ (
previous.rows ?? {}
);
const afterRows =
/** @type {Record<string, Record<string, unknown>>} */ (current.rows ?? {});
const rowNames = new Set([
...Object.keys(beforeRows),
...Object.keys(afterRows),
]);
for (const rowName of [...rowNames].sort()) {
const beforeRow = beforeRows[rowName];
const afterRow = afterRows[rowName];
if (!beforeRow || !afterRow) {
const changeImpact = beforeRow ? "breaking" : "additive";
impact = strongestImpact(impact, changeImpact);
changes.push({
changeId: changeId(
registryId,
rowName,
"*",
beforeRow ? "removed" : "added",
),
registryId,
rowName,
field: "*",
kind: beforeRow ? "row-removed" : "row-added",
impact: changeImpact,
});
continue;
}
const fields = new Set([
...Object.keys(beforeRow),
...Object.keys(afterRow),
]);
for (const field of [...fields].sort()) {
const beforeHas = Object.hasOwn(beforeRow, field);
const afterHas = Object.hasOwn(afterRow, field);
const beforeValue = beforeRow[field];
const afterValue = afterRow[field];
if (
beforeHas &&
afterHas &&
canonicalRegistryJson(beforeValue) ===
canonicalRegistryJson(afterValue)
) {
continue;
}
let kind;
let changeImpact;
if (!beforeHas) {
kind = "field-added";
changeImpact = "additive";
} else if (!afterHas) {
kind = "field-removed";
changeImpact = "breaking";
} else if (valueType(beforeValue) !== valueType(afterValue)) {
kind = "field-type-changed";
changeImpact = "breaking";
} else if (
Array.isArray(beforeValue) &&
Array.isArray(afterValue) &&
beforeValue.some(
(item) =>
!afterValue.some(
(candidate) =>
canonicalRegistryJson(candidate) ===
canonicalRegistryJson(item),
),
)
) {
kind = "allowed-value-removed";
changeImpact = "breaking";
} else {
kind = "field-changed";
changeImpact = breakingFields.has(field)
? "breaking"
: "behavior-change";
}
impact = strongestImpact(impact, changeImpact);
changes.push({
changeId: changeId(registryId, rowName, field, kind),
registryId,
rowName,
field,
kind,
impact: changeImpact,
before: canonicalizeRegistryValue(beforeValue),
after: canonicalizeRegistryValue(afterValue),
});
}
}
}
return Object.freeze({
impact,
changes: Object.freeze(changes),
});
}
/**
* @param {Readonly<Record<string, unknown>>} snapshot
* @param {Readonly<Record<string, unknown>>} approval
*/
export function verifyRegistryBaselineApproval(snapshot, approval) {
const actualDigest = registrySnapshotDigest(snapshot);
const approvedDigest = approval.snapshotDigest;
return Object.freeze({
passed:
approval.schemaVersion === 1 &&
typeof approval.owner === "string" &&
approval.owner.length > 0 &&
typeof approval.approvedAt === "string" &&
approvedDigest === actualDigest,
actualDigest,
approvedDigest:
typeof approvedDigest === "string" ? approvedDigest : "missing",
});
}
/**
* @param {ReturnType<typeof diffRegistrySnapshots>} diff
* @param {Readonly<Record<string, unknown>>} evidenceFile
*/
export function validateBreakingEvidence(diff, evidenceFile) {
const evidence = new Map(
/** @type {Array<Record<string, unknown>>} */ (
evidenceFile.changes ?? []
).map((entry) => [entry.changeId, entry]),
);
const failures = [];
for (const change of diff.changes.filter(
(entry) => entry.impact === "breaking",
)) {
const entry = evidence.get(change.changeId);
if (!entry) {
failures.push(`breaking change missing evidence: ${change.changeId}`);
continue;
}
for (const field of [
"versionBump",
"migration",
"compatibilityWindow",
"rollback",
"owner",
]) {
if (typeof entry[field] !== "string" || entry[field].trim().length === 0) {
failures.push(
`breaking change ${change.changeId} missing non-empty ${field}`,
);
}
}
}
return Object.freeze({
passed: failures.length === 0,
failures: Object.freeze(failures),
});
}
scripts/serve-static.mjs
+47
View File
@@ -0,0 +1,47 @@
import { createReadStream } from "node:fs";
import { access, stat } from "node:fs/promises";
import { createServer } from "node:http";
import path from "node:path";
const root = path.resolve(process.argv[2] ?? "artifacts/storybook/static");
const port = Number(process.argv[3] ?? 6006);
const contentTypes = /** @type {Readonly<Record<string, string>>} */ ({
".css": "text/css; charset=utf-8",
".html": "text/html; charset=utf-8",
".js": "text/javascript; charset=utf-8",
".json": "application/json; charset=utf-8",
".svg": "image/svg+xml",
".png": "image/png",
});
await access(root);
const server = createServer(async (request, response) => {
try {
const url = new URL(request.url ?? "/", `http://127.0.0.1:${port}`);
const decoded = decodeURIComponent(url.pathname);
const requested = path.resolve(root, `.${decoded}`);
if (requested !== root && !requested.startsWith(`${root}${path.sep}`)) {
response.writeHead(403).end();
return;
}
const details = await stat(requested).catch(() => null);
const file = details?.isDirectory()
? path.join(requested, "index.html")
: requested;
await access(file);
response.writeHead(200, {
"Content-Type":
contentTypes[path.extname(file)] ?? "application/octet-stream",
"Cache-Control": "no-store",
});
createReadStream(file).pipe(response);
} catch {
response.writeHead(404).end();
}
});
server.listen(port, "127.0.0.1", () => {
process.stdout.write(`Static evidence server: ${root} on ${port}\n`);
});
for (const signal of ["SIGINT", "SIGTERM"]) {
process.on(signal, () => server.close(() => process.exit(0)));
}
scripts/test-sample-removal.mjs
+37 -1
View File
@@ -18,6 +18,7 @@ const featureOwnedPaths = [
featureSource, featureSource,
featureTests, featureTests,
"tests/e2e/reference-form.spec.js", "tests/e2e/reference-form.spec.js",
"tests/mocks",
]; ];
const copyTargets = [ const copyTargets = [
"src", "src",
@@ -41,6 +42,7 @@ const copyTargets = [
const emptyContracts = `import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.js"; const emptyContracts = `import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.js";
import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.js"; import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.js";
import { PLATFORM_SCHEMA_REGISTRY } from "../contracts/schema-registry.js";
export const INSTALLED_FEATURE_CONTRACTS = export const INSTALLED_FEATURE_CONTRACTS =
/** @type {readonly unknown[]} */ (Object.freeze([])); /** @type {readonly unknown[]} */ (Object.freeze([]));
@@ -48,6 +50,7 @@ export const ROUTE_REGISTRY = PLATFORM_ROUTE_REGISTRY;
export const ROUTE_RUNTIME_CONTRACT = PLATFORM_ROUTE_RUNTIME_CONTRACT; export const ROUTE_RUNTIME_CONTRACT = PLATFORM_ROUTE_RUNTIME_CONTRACT;
export const API_OPERATIONS = Object.freeze({}); export const API_OPERATIONS = Object.freeze({});
export const QUERY_REGISTRY = Object.freeze({}); export const QUERY_REGISTRY = Object.freeze({});
export const SCHEMA_REGISTRY = PLATFORM_SCHEMA_REGISTRY;
export const NAVIGATION_ROUTES = Object.freeze( export const NAVIGATION_ROUTES = Object.freeze(
Object.values(ROUTE_REGISTRY) Object.values(ROUTE_REGISTRY)
.filter((definition) => definition.navigationOrder !== null) .filter((definition) => definition.navigationOrder !== null)
@@ -145,6 +148,39 @@ await writeFile(
path.join(fixtureRoot, "src/features/installed-feature-messages.js"), path.join(fixtureRoot, "src/features/installed-feature-messages.js"),
emptyMessages, emptyMessages,
); );
const governanceFile = path.join(
fixtureRoot,
"config/contracts/registry-governance.json",
);
const removalGovernance = JSON.parse(await readFile(governanceFile, "utf8"));
removalGovernance.registries = removalGovernance.registries.map(
/** @param {Record<string, unknown>} registry */
(registry) => ({
...registry,
...(Array.isArray(registry.consumers)
? {
consumers: registry.consumers.filter(
/** @param {{path?: string}} consumer */
(consumer) =>
!consumer.path?.includes("features/reference-feature"),
),
}
: {}),
...(Array.isArray(registry.consumerDirectories)
? {
consumerDirectories: registry.consumerDirectories.filter(
/** @param {string} directory */
(directory) =>
!directory.includes("features/reference-feature"),
),
}
: {}),
}),
);
await writeFile(
governanceFile,
`${JSON.stringify(removalGovernance, null, 2)}\n`,
);
/** @type {string[]} */ /** @type {string[]} */
const residue = []; const residue = [];
@@ -165,7 +201,7 @@ for (const root of ["src", "tests"]) {
const checks = [ const checks = [
["typecheck", runPnpm("check:types")], ["typecheck", runPnpm("check:types")],
["architecture", runPnpm("check:architecture")], ["architecture", runPnpm("check:architecture")],
["registry", runPnpm("check:registries")], ["registry-structure", runPnpm("check:registries:structure")],
["unit-integration", runPnpm("test:all")], ["unit-integration", runPnpm("test:all")],
[ [
"home-smoke", "home-smoke",
scripts/update-registry-baseline.mjs
+41
View File
@@ -0,0 +1,41 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import { registrySnapshotDigest } from "./lib/registry-compatibility.mjs";
const inputPath =
process.argv[2] ?? "artifacts/quality/registry-current-snapshot.json";
const outputPath =
process.argv[3] ?? "config/contracts/registry-baseline.json";
const owner = process.env.REGISTRY_BASELINE_OWNER;
const reason = process.env.REGISTRY_BASELINE_REASON;
if (!owner || !reason) {
process.stderr.write(
"REGISTRY_BASELINE_OWNER and REGISTRY_BASELINE_REASON are required.\n",
);
process.exit(1);
}
const input = JSON.parse(await readFile(inputPath, "utf8"));
const snapshot = input.registries
? { schemaVersion: 2, registries: input.registries }
: input;
const digest = registrySnapshotDigest(snapshot);
await mkdir(path.dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${JSON.stringify(snapshot, null, 2)}\n`);
await writeFile(
"config/contracts/registry-baseline.approval.json",
`${JSON.stringify(
{
schemaVersion: 1,
snapshotDigest: digest,
owner,
reason,
approvedAt: new Date().toISOString(),
},
null,
2,
)}\n`,
);
process.stdout.write(`Registry baseline updated: ${digest}\n`);
src/bootstrap/main.jsx
+2
View File
@@ -20,6 +20,8 @@ const root = createRoot(rootElement);
async function boot() { async function boot() {
try { try {
const composition = await createRuntimeComposition(); const composition = await createRuntimeComposition();
document.documentElement.dataset.buildId = composition.release.buildId;
document.documentElement.dataset.releaseId = composition.release.releaseId;
initializeColorScheme(composition.application.preferences); initializeColorScheme(composition.application.preferences);
root.render(<RuntimeApplication composition={composition} />); root.render(<RuntimeApplication composition={composition} />);
} catch (error) { } catch (error) {
src/contracts/schema-registry.js
+27
View File
@@ -0,0 +1,27 @@
/**
* @typedef {{
* schemaId: string,
* boundary: "route-params" | "route-search" |
* "route-search-api-request" | "api-request" | "api-response",
* owner: string,
* runtime: "zod"
* }} SchemaDefinition
*/
export const PLATFORM_SCHEMA_REGISTRY =
/** @type {Readonly<Record<string, Readonly<SchemaDefinition>>>} */ (
Object.freeze({
none: Object.freeze({
schemaId: "none",
boundary: "route-params",
owner: "feature-frontend-routing-release-recovery-runtime",
runtime: "zod",
}),
NotFoundSplat: Object.freeze({
schemaId: "NotFoundSplat",
boundary: "route-params",
owner: "feature-frontend-routing-release-recovery-runtime",
runtime: "zod",
}),
})
);
src/features/installed-feature-contracts.js
+5
View File
@@ -1,5 +1,6 @@
import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.js"; import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.js";
import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.js"; import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.js";
import { PLATFORM_SCHEMA_REGISTRY } from "../contracts/schema-registry.js";
import { REFERENCE_FEATURE_CONTRACT } from "./reference-feature/contracts/reference-feature-contract.js"; import { REFERENCE_FEATURE_CONTRACT } from "./reference-feature/contracts/reference-feature-contract.js";
export const INSTALLED_FEATURE_CONTRACTS = Object.freeze([ export const INSTALLED_FEATURE_CONTRACTS = Object.freeze([
@@ -20,6 +21,10 @@ export const API_OPERATIONS = Object.freeze({
export const QUERY_REGISTRY = Object.freeze({ export const QUERY_REGISTRY = Object.freeze({
...REFERENCE_FEATURE_CONTRACT.queryRegistry, ...REFERENCE_FEATURE_CONTRACT.queryRegistry,
}); });
export const SCHEMA_REGISTRY = Object.freeze({
...PLATFORM_SCHEMA_REGISTRY,
...REFERENCE_FEATURE_CONTRACT.schemas,
});
export const NAVIGATION_ROUTES = Object.freeze( export const NAVIGATION_ROUTES = Object.freeze(
Object.values(ROUTE_REGISTRY) Object.values(ROUTE_REGISTRY)
src/features/reference-feature/contracts/reference-feature-contract.js
+38
View File
@@ -14,6 +14,44 @@ export const referenceQueryKeys = Object.freeze({
export const REFERENCE_FEATURE_CONTRACT = Object.freeze({ export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
featureId: REFERENCE_FEATURE_ID, featureId: REFERENCE_FEATURE_ID,
schemas: Object.freeze({
ReferenceResourceParams: Object.freeze({
schemaId: "ReferenceResourceParams",
boundary: "route-params",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
}),
ReferenceResourceListQuery: Object.freeze({
schemaId: "ReferenceResourceListQuery",
boundary: "route-search-api-request",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
}),
CreateReferenceResourceCommand: Object.freeze({
schemaId: "CreateReferenceResourceCommand",
boundary: "api-request",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
}),
NoRequest: Object.freeze({
schemaId: "NoRequest",
boundary: "api-request",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
}),
ReferenceResourceListPayload: Object.freeze({
schemaId: "ReferenceResourceListPayload",
boundary: "api-response",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
}),
ReferenceResourcePayload: Object.freeze({
schemaId: "ReferenceResourcePayload",
boundary: "api-response",
owner: "feature-frontend-reference-feature-vertical-slice",
runtime: "zod",
}),
}),
routes: Object.freeze({ routes: Object.freeze({
REFERENCE_RESOURCE_LIST: Object.freeze({ REFERENCE_RESOURCE_LIST: Object.freeze({
routeId: "REFERENCE_RESOURCE_LIST", routeId: "REFERENCE_RESOURCE_LIST",
src/features/reference-feature/contracts/reference-schemas.ts
+1
View File
@@ -39,6 +39,7 @@ const payloadSchemas = {
const requestSchemas = { const requestSchemas = {
ReferenceResourceListQuery: referenceResourceListQuerySchema, ReferenceResourceListQuery: referenceResourceListQuerySchema,
NoRequest: z.object({}).strict(),
CreateReferenceResourceCommand: z CreateReferenceResourceCommand: z
.object({ .object({
name: z.string().trim().min(1).max(120), name: z.string().trim().min(1).max(120),
src/presentation/design-system/design-system.stories.tsx
+128
View File
@@ -0,0 +1,128 @@
import type { Meta, StoryObj } from "@storybook/react-vite";
import { expect, userEvent, within } from "storybook/test";
import { useState } from "react";
import {
Alert,
Badge,
Button,
Card,
Dialog,
Menu,
ProgressBar,
Skeleton,
Tabs,
TextArea,
TextField,
} from "./index.js";
const meta = {
title: "Platform/Design System",
component: Button,
tags: ["autodocs"],
parameters: {
layout: "padded",
},
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Primitives: Story = {
render: () => (
<div className="ui-stack">
<Card title="Actions and status">
<div className="ui-cluster">
<Button>Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="danger">Danger</Button>
<Button pending pendingLabel="Processing">
Save
</Button>
</div>
<div className="ui-cluster">
<Badge variant="neutral">Neutral</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="danger">Danger</Badge>
</div>
</Card>
<TextField
description="A stable accessible description"
label="Name"
placeholder="Example"
/>
<TextField error="Enter a name" label="Invalid name" value="" readOnly />
<TextArea
defaultValue="Long-form content"
label="Notes"
maxLength={100}
/>
<Alert title="Platform status" variant="info">
The component workshop uses the same tokens and providers as the app.
</Alert>
<ProgressBar label="Build readiness" value={72} />
<Skeleton label="Loading example" />
</div>
),
};
function OverlayExample() {
const [open, setOpen] = useState(false);
return (
<div className="ui-stack">
<Button onClick={() => setOpen(true)}>Open dialog</Button>
<Dialog
actions={<Button onClick={() => setOpen(false)}>Confirm</Button>}
onClose={() => setOpen(false)}
open={open}
title="Confirm platform action"
>
Keyboard dismissal must restore focus to the trigger.
</Dialog>
<Menu
items={[
{ id: "first", label: "First action", onSelect() {} },
{ id: "second", label: "Second action", onSelect() {} },
]}
triggerLabel="Open menu"
/>
<Tabs
defaultValue="one"
label="Example sections"
tabs={[
{ id: "one", label: "One", panel: "First panel" },
{ id: "two", label: "Two", panel: "Second panel" },
]}
/>
</div>
);
}
export const OverlayInteraction: Story = {
render: () => <OverlayExample />,
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
const trigger = canvas.getByRole("button", { name: "Open dialog" });
await userEvent.click(trigger);
const dialog = within(document.body).getByRole("dialog", {
name: "Confirm platform action",
});
await expect(dialog).toBeVisible();
await userEvent.keyboard("{Escape}");
await expect(dialog).not.toBeVisible();
await expect(trigger).toHaveFocus();
},
};
export const LongPseudoLikeContent: Story = {
render: () => (
<Card title="[!! Ćømƥøñëñţ ţøķëñ åñđ ļøñğ ţëжţ vëŕïƒïćåţïøñ !!]">
<p>
[!! Ţhïš šţøŕÿ vëŕïƒïëš ţhåţ å ƥŕïmïţïvë ŕëmåïñš ŕëåđåɓļë
ïñ å ćømƥåćţ ćøñţåïñëŕ. !!]
</p>
<Button>[!! Ćøñţïñüë !!]</Button>
</Card>
),
};
tests/e2e/accessibility.spec.js
+1 -1
View File
@@ -1,5 +1,5 @@
import AxeBuilder from "@axe-core/playwright"; import AxeBuilder from "@axe-core/playwright";
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js"; import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js";
for (const route of Object.values(ROUTE_REGISTRY).map((definition) => { for (const route of Object.values(ROUTE_REGISTRY).map((definition) => {
tests/e2e/app-shell.spec.js
+15 -1
View File
@@ -1,4 +1,5 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
import { successEnvelope } from "../mocks/contracts/envelopes.js";
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js"; import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js";
test("boots the public app shell", async ({ page }) => { test("boots the public app shell", async ({ page }) => {
@@ -32,6 +33,19 @@ test("opens the protected integration route through the local demo seam", async
(definition) => definition.access === "integration-defined", (definition) => definition.access === "integration-defined",
); );
if (!protectedRoute) throw new Error("An integration route is required"); if (!protectedRoute) throw new Error("An integration route is required");
await page.route(
"http://localhost:8080/api/reference-resources?*",
(route) =>
route.fulfill({
json: successEnvelope([
{
id: "browser-reference",
name: "Browser reference",
createdAt: "2026-07-26T00:00:00.000Z",
},
]),
}),
);
await page.goto(protectedRoute.path); await page.goto(protectedRoute.path);
await expect( await expect(
page.getByRole("heading", { name: "세션이 필요합니다." }), page.getByRole("heading", { name: "세션이 필요합니다." }),
tests/e2e/compact-smoke.spec.js
+17
View File
@@ -0,0 +1,17 @@
import { expect, test } from "../support/browser/strict-browser-test.js";
test("boots and navigates the compact production shell", async ({ page }) => {
await page.goto("/");
await expect(page.getByRole("main")).toBeVisible();
const menu = page.getByRole("button", { name: "메뉴", exact: true });
await expect(menu).toHaveCSS("min-width", "44px");
await menu.click();
await expect(page.getByRole("navigation", { name: "주요 탐색" })).toBeVisible();
await page.getByRole("link", { name: "UI 구성요소" }).click();
await expect(page).toHaveURL(/\/examples\/ui$/);
await expect(page.locator("html")).toHaveAttribute("data-build-id", "local-build");
const overflow = await page.evaluate(
() => document.documentElement.scrollWidth - window.innerWidth,
);
expect(overflow).toBeLessThanOrEqual(1);
});
tests/e2e/design-system-interactions.spec.js
+1 -1
View File
@@ -1,4 +1,4 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
test("runs menu typeahead, tabs and duplicate toast interactions", async ({ test("runs menu typeahead, tabs and duplicate toast interactions", async ({
page, page,
tests/e2e/i18n.spec.js
+1 -1
View File
@@ -1,4 +1,4 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
test("switches the shell locale and keeps pseudo-locale copy within compact layout", async ({ test("switches the shell locale and keeps pseudo-locale copy within compact layout", async ({
page, page,
tests/e2e/reference-form.spec.js
+1 -1
View File
@@ -1,4 +1,4 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
/** @param {import("@playwright/test").Page} page */ /** @param {import("@playwright/test").Page} page */
async function openReferenceForm(page) { async function openReferenceForm(page) {
tests/e2e/responsive.spec.js
+1 -1
View File
@@ -1,4 +1,4 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
test("reflows the UI gallery at the 320px minimum without horizontal overflow", async ({ test("reflows the UI gallery at the 320px minimum without horizontal overflow", async ({
page, page,
tests/e2e/theme.spec.js
+1 -1
View File
@@ -1,5 +1,5 @@
import AxeBuilder from "@axe-core/playwright"; import AxeBuilder from "@axe-core/playwright";
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
test("persists an explicit color scheme through the storage contract", async ({ test("persists an explicit color scheme through the storage contract", async ({
page, page,
tests/e2e/ui-gallery.spec.js
+1 -1
View File
@@ -1,4 +1,4 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "../support/browser/strict-browser-test.js";
test("validates and reports the common text-field flow", async ({ page }) => { test("validates and reports the common text-field flow", async ({ page }) => {
await page.goto("/examples/ui"); await page.goto("/examples/ui");
tests/features/reference-feature/reference-production-vertical.test.tsx
+12 -29
View File
@@ -1,7 +1,5 @@
// @vitest-environment jsdom // @vitest-environment jsdom
import { HttpResponse, http } from "msw";
import { setupServer } from "msw/node";
import { render, screen } from "@testing-library/react"; import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event"; import userEvent from "@testing-library/user-event";
import { import {
@@ -16,6 +14,9 @@ import {
import { createRuntimeComposition } from "../../../src/bootstrap/create-runtime-composition.js"; import { createRuntimeComposition } from "../../../src/bootstrap/create-runtime-composition.js";
import { RuntimeApplication } from "../../../src/bootstrap/runtime-application.jsx"; import { RuntimeApplication } from "../../../src/bootstrap/runtime-application.jsx";
import { createBootstrapHandlers } from "../../mocks/handlers/bootstrap.js";
import { createReferenceScenarioHandlers } from "../../mocks/handlers/reference-resources.js";
import { createStrictMockServer } from "../../mocks/server.js";
const runtimeConfig = { const runtimeConfig = {
APP_ENV: "local", APP_ENV: "local",
@@ -56,41 +57,23 @@ const releaseManifest = {
const listRequests = vi.fn(); const listRequests = vi.fn();
const createRequests = vi.fn(); const createRequests = vi.fn();
const resources = [{ id: "reference-1", name: "Existing" }]; const resources = [{ id: "reference-1", name: "Existing" }];
const server = setupServer( const mockApi = createStrictMockServer(
http.get("http://app.test/config.json", () => ...createBootstrapHandlers(runtimeConfig, releaseManifest),
HttpResponse.json(runtimeConfig), ...createReferenceScenarioHandlers({
), resources,
http.get("http://app.test/release-manifest.json", () => onList: listRequests,
HttpResponse.json(releaseManifest), onCreate: createRequests,
),
http.get("https://api.test/api/reference-resources", ({ request }) => {
listRequests(new URL(request.url).search);
return HttpResponse.json({
success: true,
data: resources,
meta: { requestId: "request-list", traceId: "trace-list" },
});
}),
http.post("https://api.test/api/reference-resources", async ({ request }) => {
const body = (await request.json()) as { name: string };
createRequests(body);
const created = { id: "reference-created", name: body.name };
resources.push(created);
return HttpResponse.json({
success: true,
data: created,
meta: { requestId: "request-create", traceId: "trace-create" },
});
}), }),
); );
beforeAll(() => server.listen({ onUnhandledRequest: "error" })); beforeAll(mockApi.listen);
afterEach(() => { afterEach(() => {
mockApi.reset();
listRequests.mockClear(); listRequests.mockClear();
createRequests.mockClear(); createRequests.mockClear();
resources.splice(1); resources.splice(1);
}); });
afterAll(() => server.close()); afterAll(mockApi.close);
const absoluteFetch: typeof fetch = (input, init) => { const absoluteFetch: typeof fetch = (input, init) => {
if (input instanceof Request) return fetch(input, init); if (input instanceof Request) return fetch(input, init);
tests/fixtures/registry/compatibility/semantic-diff.json
Vendored
+225
View File
@@ -0,0 +1,225 @@
{
"schemaVersion": 1,
"cases": [
{
"id": "ordering-only",
"expected": "none",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": {
"A": { "path": "/a", "tags": ["one", "two"] },
"B": { "path": "/b", "tags": ["three"] }
}
}
]
},
"after": {
"registries": [
{
"rows": {
"B": { "tags": ["three"], "path": "/b" },
"A": { "tags": ["two", "one"], "path": "/a" }
},
"contract": { "breakingFields": ["path"] },
"registryId": "FE-REG-TEST"
}
],
"schemaVersion": 2
}
},
{
"id": "row-addition",
"expected": "additive",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/a" } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": {
"A": { "path": "/a" },
"B": { "path": "/b" }
}
}
]
}
},
{
"id": "behavior-change",
"expected": "behavior-change",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/a", "owner": "one" } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/a", "owner": "two" } }
}
]
}
},
{
"id": "row-removal",
"expected": "breaking",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": {
"A": { "path": "/a" },
"B": { "path": "/b" }
}
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/a" } }
}
]
}
},
{
"id": "field-type-narrowing",
"expected": "breaking",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "limit": 10 } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "limit": "10" } }
}
]
}
},
{
"id": "route-path-change",
"expected": "breaking",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/before" } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/after" } }
}
]
}
},
{
"id": "registry-contract-narrowing",
"expected": "breaking",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": {
"breakingFields": ["path"],
"allowedValues": { "kind": ["one", "two"] }
},
"rows": { "A": { "path": "/a", "kind": "one" } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": {
"breakingFields": ["path"],
"allowedValues": { "kind": ["one"] }
},
"rows": { "A": { "path": "/a", "kind": "one" } }
}
]
}
}
],
"breakingEvidence": {
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/before" } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": { "breakingFields": ["path"] },
"rows": { "A": { "path": "/after" } }
}
]
}
},
"tamperedApproval": {
"snapshot": {
"schemaVersion": 2,
"registries": []
},
"approval": {
"schemaVersion": 1,
"snapshotDigest": "tampered",
"owner": "fixture-owner",
"approvedAt": "2026-07-26T00:00:00.000Z"
}
}
}
tests/fixtures/registry/compatibility/tampered-approval.json
Vendored
+6
View File
@@ -0,0 +1,6 @@
{
"schemaVersion": 1,
"snapshotDigest": "0000000000000000000000000000000000000000000000000000000000000000",
"owner": "negative-fixture",
"approvedAt": "2026-07-26T00:00:00.000Z"
}
tests/fixtures/test-evidence/forbidden/full-screen-mask.fixture
Vendored
+5
View File
@@ -0,0 +1,5 @@
test("false visual pass", async ({ page }) => {
await expect(page).toHaveScreenshot({
mask: [page.locator("body")]
});
});
tests/fixtures/test-evidence/forbidden/unowned-skip.fixture
Vendored
+1
View File
@@ -0,0 +1 @@
test.skip("unowned indefinite quarantine", async () => {});
tests/mocks/contracts/envelopes.ts
+30
View File
@@ -0,0 +1,30 @@
export function successEnvelope<Value>(
data: Value,
requestId = "fixture-request",
) {
return Object.freeze({
success: true as const,
data: structuredClone(data),
meta: Object.freeze({
requestId,
traceId: "fixture-trace",
}),
});
}
export function failureEnvelope(
code: string,
details?: Readonly<Record<string, unknown>>,
) {
return Object.freeze({
success: false as const,
error: Object.freeze({
code,
...(details ? { details: structuredClone(details) } : {}),
}),
meta: Object.freeze({
requestId: "fixture-request",
traceId: "fixture-trace",
}),
});
}
tests/mocks/handlers/bootstrap.ts
+16
View File
@@ -0,0 +1,16 @@
import { http, HttpResponse } from "msw";
export function createBootstrapHandlers(
runtimeConfig: Readonly<Record<string, unknown>>,
releaseManifest: Readonly<Record<string, unknown>>,
baseUrl = "http://app.test",
) {
return [
http.get(`${baseUrl}/config.json`, () =>
HttpResponse.json(structuredClone(runtimeConfig)),
),
http.get(`${baseUrl}/release-manifest.json`, () =>
HttpResponse.json(structuredClone(releaseManifest)),
),
] as const;
}
tests/mocks/handlers/reference-resources.ts
+171
View File
@@ -0,0 +1,171 @@
import { delay, http, HttpResponse } from "msw";
import {
failureEnvelope,
successEnvelope,
} from "../contracts/envelopes.js";
import type { HttpScenarioId } from "../scenarios/catalog.js";
import { assertOperationScenario } from "../scenarios/catalog.js";
export type ReferenceResourceFixture = Readonly<{
id: string;
name: string;
createdAt?: string;
}>;
type ScenarioOptions = Readonly<{
baseUrl?: string;
scenarios?: Partial<
Record<
| "LIST_REFERENCE_RESOURCES"
| "CREATE_REFERENCE_RESOURCE"
| "GET_REFERENCE_RESOURCE",
HttpScenarioId
>
>;
resources?: ReferenceResourceFixture[];
onList?(search: string): void;
onCreate?(body: Readonly<Record<string, unknown>>): void;
}>;
const DEFAULT_RESOURCE = Object.freeze({
id: "reference-1",
name: "Reference",
createdAt: "2026-07-26T00:00:00.000Z",
});
async function scenarioResponse(
scenario: HttpScenarioId,
payload: unknown,
attempt: number,
) {
if (scenario === "slow") await delay(50);
if (scenario === "timeout") await delay(30_000);
if (scenario === "network-error") return HttpResponse.error();
if (scenario === "content-type-mismatch") {
return new HttpResponse("<html>not json</html>", {
headers: { "Content-Type": "text/html" },
});
}
if (scenario === "malformed-json") {
return new HttpResponse("{invalid", {
headers: { "Content-Type": "application/json" },
});
}
if (scenario === "envelope-mismatch") {
return HttpResponse.json({ data: payload });
}
if (scenario === "schema-mismatch") {
return HttpResponse.json(successEnvelope({ unexpected: true }));
}
if (
scenario === "auth-persistent-401" ||
(scenario === "auth-recover-once" && attempt === 1)
) {
return HttpResponse.json(failureEnvelope("AUTH_REQUIRED"), {
status: 401,
});
}
if (scenario === "forbidden-403") {
return HttpResponse.json(failureEnvelope("FORBIDDEN"), { status: 403 });
}
if (scenario === "not-found-404") {
return HttpResponse.json(failureEnvelope("NOT_FOUND"), { status: 404 });
}
if (scenario === "conflict-409") {
return HttpResponse.json(failureEnvelope("CONFLICT"), { status: 409 });
}
if (scenario === "validation-422") {
return HttpResponse.json(
failureEnvelope("VALIDATION_REJECTED", {
issues: [{ path: "name", code: "too_small" }],
}),
{ status: 422 },
);
}
if (scenario === "rate-limited-429") {
return HttpResponse.json(failureEnvelope("RATE_LIMITED"), {
status: 429,
headers: { "Retry-After": "1" },
});
}
if (
scenario === "server-terminal-500" ||
(scenario === "server-retry-success" && attempt === 1)
) {
return HttpResponse.json(failureEnvelope("SERVER_FAILURE"), {
status: 503,
});
}
return HttpResponse.json(successEnvelope(payload));
}
export function createReferenceScenarioHandlers(options: ScenarioOptions = {}) {
const baseUrl = options.baseUrl ?? "https://api.test";
const resources = options.resources ?? [{ ...DEFAULT_RESOURCE }];
const attempts = new Map<string, number>();
const scenarioFor = (
operationId: keyof NonNullable<ScenarioOptions["scenarios"]>,
) =>
assertOperationScenario(
operationId,
options.scenarios?.[operationId] ?? "success",
);
const nextAttempt = (operationId: string) => {
const next = (attempts.get(operationId) ?? 0) + 1;
attempts.set(operationId, next);
return next;
};
return [
http.get(`${baseUrl}/api/reference-resources`, ({ request }) => {
options.onList?.(new URL(request.url).search);
const scenario = scenarioFor("LIST_REFERENCE_RESOURCES");
const payload = scenario === "empty" ? [] : resources;
return scenarioResponse(
scenario,
payload,
nextAttempt("LIST_REFERENCE_RESOURCES"),
);
}),
http.post(
`${baseUrl}/api/reference-resources`,
async ({ request }) => {
const rawBody = await request.json();
const body =
rawBody &&
typeof rawBody === "object" &&
!Array.isArray(rawBody)
? (rawBody as Readonly<Record<string, unknown>>)
: {};
options.onCreate?.(body);
const scenario = scenarioFor("CREATE_REFERENCE_RESOURCE");
const created = {
id: "reference-created",
name: String(body.name ?? "Created"),
createdAt: "2026-07-26T00:00:00.000Z",
};
if (scenario === "success") resources.push(created);
return scenarioResponse(
scenario,
created,
nextAttempt("CREATE_REFERENCE_RESOURCE"),
);
},
),
http.get(
`${baseUrl}/api/reference-resources/:resourceId`,
({ params }) => {
const scenario = scenarioFor("GET_REFERENCE_RESOURCE");
const resource =
resources.find((entry) => entry.id === params.resourceId) ??
DEFAULT_RESOURCE;
return scenarioResponse(
scenario,
resource,
nextAttempt("GET_REFERENCE_RESOURCE"),
);
},
),
] as const;
}
tests/mocks/scenarios/catalog.ts
+45
View File
@@ -0,0 +1,45 @@
export const HTTP_SCENARIO_IDS = Object.freeze([
"success",
"empty",
"slow",
"network-error",
"timeout",
"aborted",
"content-type-mismatch",
"malformed-json",
"envelope-mismatch",
"schema-mismatch",
"auth-recover-once",
"auth-persistent-401",
"forbidden-403",
"not-found-404",
"conflict-409",
"validation-422",
"rate-limited-429",
"server-retry-success",
"server-terminal-500",
] as const);
export type HttpScenarioId = (typeof HTTP_SCENARIO_IDS)[number];
export const OPERATION_SCENARIO_CATALOG = Object.freeze({
LIST_REFERENCE_RESOURCES: HTTP_SCENARIO_IDS,
CREATE_REFERENCE_RESOURCE: Object.freeze(
HTTP_SCENARIO_IDS.filter(
(scenario) => !["empty", "aborted"].includes(scenario),
),
),
GET_REFERENCE_RESOURCE: HTTP_SCENARIO_IDS,
} satisfies Readonly<Record<string, readonly HttpScenarioId[]>>);
export function assertOperationScenario(
operationId: keyof typeof OPERATION_SCENARIO_CATALOG,
scenario: HttpScenarioId,
) {
if (!OPERATION_SCENARIO_CATALOG[operationId].includes(scenario)) {
throw new Error(
`Scenario ${scenario} is not declared for ${operationId}`,
);
}
return scenario;
}
tests/mocks/server.ts
+13
View File
@@ -0,0 +1,13 @@
import { setupServer } from "msw/node";
export function createStrictMockServer(
...handlers: Parameters<typeof setupServer>
) {
const server = setupServer(...handlers);
return Object.freeze({
server,
listen: () => server.listen({ onUnhandledRequest: "error" }),
reset: () => server.resetHandlers(),
close: () => server.close(),
});
}
tests/storybook/workshop.spec.ts
+24
View File
@@ -0,0 +1,24 @@
import AxeBuilder from "@axe-core/playwright";
import {
expect,
test,
} from "../support/browser/strict-browser-test.js";
test("runs the isolated overlay interaction with blocking accessibility", async ({
page,
}) => {
await page.goto(
"/iframe.html?id=platform-design-system--overlay-interaction&viewMode=story",
);
const trigger = page.getByRole("button", { name: "Open dialog" });
await expect(trigger).toBeVisible();
await trigger.click();
await expect(
page.getByRole("dialog", { name: "Confirm platform action" }),
).toBeVisible();
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
await page.keyboard.press("Escape");
await expect(trigger).toBeFocused();
});
tests/support/browser/strict-browser-test.ts
+46
View File
@@ -0,0 +1,46 @@
import {
expect,
test as base,
type ConsoleMessage,
type Page,
} from "@playwright/test";
function ignoredConsole(message: ConsoleMessage) {
return (
message.type() === "warning" &&
message.text().includes("NO_COLOR")
);
}
export const test = base.extend({
page: async ({ page }, use) => {
const failures: string[] = [];
const onConsole = (message: ConsoleMessage) => {
if (
["error", "warning"].includes(message.type()) &&
!ignoredConsole(message)
) {
failures.push(`console:${message.type()}:${message.text()}`);
}
};
const onPageError = (error: Error) => {
failures.push(`pageerror:${error.name}`);
};
const onRequestFailed = (request: import("@playwright/test").Request) => {
failures.push(
`requestfailed:${request.method()}:${new URL(request.url()).pathname}:${request.failure()?.errorText ?? "unknown"}`,
);
};
page.on("console", onConsole);
page.on("pageerror", onPageError);
page.on("requestfailed", onRequestFailed);
await use(page);
page.off("console", onConsole);
page.off("pageerror", onPageError);
page.off("requestfailed", onRequestFailed);
expect(failures, "unexpected browser console/page errors").toEqual([]);
},
});
export { expect };
export type { Page };
tests/support/runtime/determinism.ts
+69
View File
@@ -0,0 +1,69 @@
import { vi } from "vitest";
export function createDeterministicClock(start = 0) {
let current = start;
return Object.freeze({
now: () => current,
sleep: async (milliseconds: number, signal?: AbortSignal) => {
if (signal?.aborted) throw new DOMException("aborted", "AbortError");
current += Math.max(0, milliseconds);
},
advance(milliseconds: number) {
current += Math.max(0, milliseconds);
},
});
}
export function createSeededRandom(seed = 1) {
let state = seed >>> 0;
return () => {
state = (state * 1_664_525 + 1_013_904_223) >>> 0;
return state / 0x1_0000_0000;
};
}
export function createControlledScheduler() {
const callbacks: Array<() => void> = [];
return Object.freeze({
callbacks,
setTimeout: vi.fn((callback: () => void) => {
callbacks.push(callback);
return callbacks.length - 1;
}),
clearTimeout: vi.fn(),
runNext() {
callbacks.shift()?.();
},
});
}
export function createRecordingStorage() {
const values = new Map<string, string>();
const operations: Array<
Readonly<{ operation: "get" | "set" | "remove"; key: string }>
> = [];
const storage: Storage = {
getItem(key) {
operations.push({ operation: "get", key });
return values.get(key) ?? null;
},
setItem(key, value) {
operations.push({ operation: "set", key });
values.set(key, value);
},
removeItem(key) {
operations.push({ operation: "remove", key });
values.delete(key);
},
clear() {
values.clear();
},
key(index) {
return [...values.keys()][index] ?? null;
},
get length() {
return values.size;
},
};
return Object.freeze({ storage, operations, values });
}
tests/unit/registry-compatibility.test.ts
+102
View File
@@ -0,0 +1,102 @@
import { describe, expect, it } from "vitest";
import {
canonicalRegistryJson,
diffRegistrySnapshots,
registrySnapshotDigest,
validateBreakingEvidence,
verifyRegistryBaselineApproval,
} from "../../scripts/lib/registry-compatibility.mjs";
function snapshot(
rows: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
) {
return {
schemaVersion: 2,
registries: [
{
registryId: "FE-REG-TEST",
contract: { breakingFields: ["path"] },
rows,
},
],
};
}
describe("registry compatibility evidence", () => {
it("canonicalizes object and primitive-array ordering", () => {
expect(
canonicalRegistryJson({
second: ["b", "a"],
first: { z: 1, a: 2 },
}),
).toBe('{"first":{"a":2,"z":1},"second":["a","b"]}');
});
it("classifies additive, behavioral and breaking actual diffs", () => {
expect(
diffRegistrySnapshots(
snapshot({ A: { path: "/a" } }),
snapshot({ A: { path: "/a" }, B: { path: "/b" } }),
).impact,
).toBe("additive");
expect(
diffRegistrySnapshots(
snapshot({ A: { path: "/a", owner: "one" } }),
snapshot({ A: { path: "/a", owner: "two" } }),
).impact,
).toBe("behavior-change");
expect(
diffRegistrySnapshots(
snapshot({ A: { path: "/a" } }),
snapshot({ A: { path: "/moved" } }),
).impact,
).toBe("breaking");
expect(
diffRegistrySnapshots(
snapshot({ A: { path: "/a" } }),
snapshot({}),
).impact,
).toBe("breaking");
});
it("verifies the approved digest and complete breaking evidence", () => {
const before = snapshot({ A: { path: "/before" } });
const after = snapshot({ A: { path: "/after" } });
const digest = registrySnapshotDigest(before);
expect(
verifyRegistryBaselineApproval(before, {
schemaVersion: 1,
snapshotDigest: digest,
owner: "platform",
approvedAt: "2026-07-26T00:00:00.000Z",
}).passed,
).toBe(true);
expect(
verifyRegistryBaselineApproval(before, {
schemaVersion: 1,
snapshotDigest: "tampered",
owner: "platform",
approvedAt: "2026-07-26T00:00:00.000Z",
}).passed,
).toBe(false);
const diff = diffRegistrySnapshots(before, after);
expect(validateBreakingEvidence(diff, { changes: [] }).passed).toBe(false);
const changeId = diff.changes[0]?.changeId;
expect(
validateBreakingEvidence(diff, {
changes: [
{
changeId,
versionBump: "2",
migration: "dual-read",
compatibilityWindow: "one release",
rollback: "restore previous registry snapshot",
owner: "platform",
},
],
}).passed,
).toBe(true);
});
});
tests/unit/registry-governance.test.js
+18 -10
View File
@@ -2,24 +2,32 @@ import { readFile } from "node:fs/promises";
import { describe, expect, it } from "vitest"; import { describe, expect, it } from "vitest";
describe("registry governance manifest", () => { describe("registry governance manifest", () => {
it("declares exactly nine single-owner registries and impact labels", async () => { it("declares ten typed, single-owner executable registries", async () => {
const governance = JSON.parse( const governance = JSON.parse(
await readFile("config/contracts/registry-governance.json", "utf8"), await readFile("config/contracts/registry-governance.json", "utf8"),
); );
const registries = const registries =
/** @type {Array<{registryId: string, owner: string}>} */ ( /** @type {Array<{
* registryId: string,
* owner: string,
* requiredFields: string[],
* fieldTypes: Record<string, string>
* }>} */ (
governance.registries governance.registries
); );
expect(governance.registries).toHaveLength(9); expect(governance.registries).toHaveLength(10);
expect(new Set(registries.map((entry) => entry.registryId)).size).toBe( expect(new Set(registries.map((entry) => entry.registryId)).size).toBe(
9, 10,
); );
expect(registries.every((entry) => entry.owner)).toBe(true); expect(registries.every((entry) => entry.owner)).toBe(true);
expect(governance.compatibilityImpact.allowed).toEqual([ expect(
"none", registries.every(
"additive", (entry) =>
"behavior-change", Array.isArray(entry.requiredFields) &&
"breaking", entry.requiredFields.length > 0 &&
]); entry.fieldTypes &&
Object.keys(entry.fieldTypes).length > 0,
),
).toBe(true);
}); });
}); });
tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-wide-light-chromium-visual-linux.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/design-system-gallery-dark-chromium-visual-linux.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 186 KiB

tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/state-surfaces-light-chromium-visual-linux.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.6 KiB

tests/visual/platform.visual.spec.ts
+43
View File
@@ -0,0 +1,43 @@
import {
expect,
test,
} from "../support/browser/strict-browser-test.js";
test("wide application shell visual contract", async ({ page }) => {
await page.setViewportSize({ width: 1440, height: 900 });
await page.goto("/");
await expect(page.getByRole("main")).toBeVisible();
await expect(page).toHaveScreenshot("app-shell-wide-light.png", {
fullPage: true,
});
});
test("compact drawer and pseudo-locale visual contract", async ({ page }) => {
await page.setViewportSize({ width: 390, height: 844 });
await page.goto("/");
await page.locator("#locale-preference").selectOption("en-XA");
await page.locator(".app-shell__menu-button").click();
await expect(page.locator(".ui-drawer")).toHaveJSProperty("open", true);
await expect(page).toHaveScreenshot("app-shell-compact-pseudo-drawer.png", {
fullPage: true,
});
});
test("design-system gallery dark visual contract", async ({ page }) => {
await page.setViewportSize({ width: 1280, height: 900 });
await page.goto("/examples/ui");
await page.locator("#theme-preference").selectOption("dark");
await expect(page.getByRole("main")).toHaveScreenshot(
"design-system-gallery-dark.png",
);
});
test("loading empty error and access surfaces visual contract", async ({
page,
}) => {
await page.setViewportSize({ width: 1280, height: 1100 });
await page.goto("/examples/states");
await expect(page.getByRole("main")).toHaveScreenshot(
"state-surfaces-light.png",
);
});
tsconfig.node.json
+1 -1
View File
@@ -4,6 +4,6 @@
"lib": ["ES2022", "DOM", "DOM.Iterable"], "lib": ["ES2022", "DOM", "DOM.Iterable"],
"types": ["node"] "types": ["node"]
}, },
"include": ["scripts", "vite.config.js"], "include": ["scripts", ".storybook", "vite.config.js"],
"exclude": ["dist", "node_modules", "tests"] "exclude": ["dist", "node_modules", "tests"]
} }
tsconfig.test.json
+1 -1
View File
@@ -10,7 +10,7 @@
"tests/**/*.ts", "tests/**/*.ts",
"tests/**/*.tsx", "tests/**/*.tsx",
"vitest.config.js", "vitest.config.js",
"playwright.config.js" "playwright*.config.js"
], ],
"exclude": [ "exclude": [
"dist", "dist",
vitest.config.js
+13 -1
View File
@@ -10,7 +10,19 @@ export default defineConfig({
testTimeout: 10_000, testTimeout: 10_000,
exclude: [...configDefaults.exclude, ".tmp/**"], exclude: [...configDefaults.exclude, ".tmp/**"],
coverage: { coverage: {
reporter: ["text", "json-summary"], provider: "v8",
reportsDirectory: "artifacts/tests/coverage",
reporter: ["text", "json-summary", "lcov"],
include: [
"src/application/policies/**/*.{js,ts}",
"src/application/use-cases/**/*.{js,ts}",
"src/contracts/diagnostics.ts",
"src/adapters/http/retry-policy.js",
"src/adapters/storage/browser-storage-adapter.js",
"src/adapters/telemetry/best-effort-telemetry.js",
"scripts/lib/registry-compatibility.mjs",
],
exclude: ["**/*.d.ts", "**/*.stories.*"],
}, },
}, },
}); });