Arch unit test additions

.snyk

@@ -1,5 +1,10 @@
 version: v1.5.0
 ignore:
+  'SNYK-JS-BRACEEXPANSION-17706650':
+    - '* > serve-handler@6.1.7 > minimatch@3.1.5 > brace-expansion':
+        reason: 'ReDoS is fixed only in brace-expansion@5.0.7, whose CJS build uses a named export (exports.expand). Docusaurus'' serve-handler pins minimatch@3.1.5, which does `var expand = require(''brace-expansion'')` and calls it directly, so 5.0.7 throws "expand is not a function". minimatch 3.x cannot be upgraded (serve-handler needs its function-default API). Every other project in the repo is on the fixed brace-expansion@5.0.7 via overrides; this path is docs-only, build-time, over repository-controlled input, and not exploitable.'
+        expires: '2026-10-01T00:00:00.000Z'
+        created: '2026-07-01T00:00:00.000Z'
   'SNYK-JS-SIRV-12558119':
     - '* > sirv@2.0.4':
         reason: 'Transitive dependency in Docusaurus; not exploitable in static site serving context (dev-only asset handler)'
@@ -93,8 +98,8 @@ ignore:
         created: '2026-06-08T00:00:00.000Z'
   'SNYK-JS-OPENTELEMETRYEXPORTERPROMETHEUS-16758050':
     - '* > @opentelemetry/exporter-prometheus@0.57.2':
-        reason: 'Requires upgrade of @opentelemetry/sdk-node to 0.217.0, which has type errors that break compilation. Created task to upgrade OTEL service to 2.x and resolve vulnerability that way.'
-        expires: '2026-07-28T00:00:00.000Z'
+        reason: 'Requires upgrade of @opentelemetry/sdk-node to 0.217.0, which has type errors that break compilation. The OTEL 2.x migration was attempted and reverted (it introduced unrelated churn and broke the coverage gate); staying on the 1.x line for now, so this ignore must persist until the migration is properly scoped into its own change.'
+        expires: '2026-10-01T00:00:00.000Z'
         created: '2026-06-01T10:00:00.000Z'
   'SNYK-JS-POSTCSSSELECTORPARSER-16873882':
     - '* > postcss-selector-parser':
@@ -165,11 +170,11 @@ ignore:
         created: '2026-06-18T00:00:00.000Z'
   'SNYK-JS-OPENTELEMETRYCORE-17373280':
     - '* > @opentelemetry/core':
-        reason: 'The fix requires migrating the Azure Functions telemetry stack from OpenTelemetry 1.x to 2.8.0 or newer. The current Azure exporter and 0.57.x SDK packages require the 1.x API family; a forced major override is type-compatible at build time but leaves mixed SDK internals. Accepted temporarily while the existing OTEL 2.x migration is completed.'
-        expires: '2026-07-18T00:00:00.000Z'
+        reason: 'The fix requires migrating the Azure Functions telemetry stack from OpenTelemetry 1.x to 2.8.0 or newer. The current Azure exporter and 0.57.x SDK packages require the 1.x API family; a forced major override is type-compatible at build time but leaves mixed SDK internals. The OTEL 2.x migration was attempted and reverted, so this remains accepted until the migration lands as its own properly scoped change.'
+        expires: '2026-10-01T00:00:00.000Z'
         created: '2026-06-18T00:00:00.000Z'
-  'SNYK-JS-BRACEEXPANSION-17706650':
-    - '* > brace-expansion@1.1.13':
-        reason: 'Transitive in Docusaurus serve-handler for local static docs serving. The fixed brace-expansion 5.x line requires minimatch 10, whose named-export API is incompatible with serve-handler 6.1.7.'
-        expires: '2026-09-30T00:00:00.000Z'
-        created: '2026-06-30T00:00:00.000Z'
+  'SNYK-JS-OPENTELEMETRYPROPAGATORJAEGER-17901201':
+    - '* > @opentelemetry/propagator-jaeger':
+        reason: 'Reintroduced by staying on the OpenTelemetry 1.x SDK line: @opentelemetry/sdk-trace-node@1.30.1 pulls @opentelemetry/propagator-jaeger@1.30.1 transitively. Fixed only in 2.9.0, which requires the OTEL 2.x migration that was reverted here (it bundled unrelated dependency churn and broke the new-code coverage gate). The Jaeger propagator is not used by the Azure Functions telemetry stack, so this is not exploitable in current usage. Accepted until the 2.x migration lands as its own scoped change; tracked alongside SNYK-JS-OPENTELEMETRYCORE-17373280 and SNYK-JS-OPENTELEMETRYEXPORTERPROMETHEUS-16758050.'
+        expires: '2026-10-01T00:00:00.000Z'
+        created: '2026-07-14T00:00:00.000Z'

apps/api/package.json

@@ -47,6 +47,7 @@
 		"@opentelemetry/api": "1.9.0"
 	},
 	"devDependencies": {
+		"@cellix/archunit-tests": "workspace:*",
 		"@cellix/config-rolldown": "workspace:*",
 		"@cellix/config-typescript": "workspace:*",
 		"@cellix/config-vitest": "workspace:*",

apps/api/src/archunit-tests/api-composition.test.ts

@@ -0,0 +1,5 @@
+import { describeApiCompositionTests } from '@cellix/archunit-tests/api';
+
+describeApiCompositionTests({
+	apiIndexPath: 'src/index.ts',
+});

apps/ui-community/package.json

@@ -14,6 +14,7 @@
 		"start": "vite",
 		"preview": "vite preview",
 		"test": "vitest run --silent --reporter=dot",
+		"test:arch": "vitest run --config vitest.arch.config.ts",
 		"test:coverage": "vitest run --coverage --silent --reporter=dot",
 		"test:watch": "vitest",
 		"storybook": "storybook dev -p 6008",
@@ -38,6 +39,7 @@
 		"react-router-dom": "catalog:"
 	},
 	"devDependencies": {
+		"@cellix/archunit-tests": "workspace:*",
 		"@cellix/config-typescript": "workspace:*",
 		"@cellix/config-vitest": "workspace:*",
 		"@cellix/local-dev": "workspace:*",

apps/ui-community/src/archunit-tests/ui-app-composition.test.ts

@@ -0,0 +1,6 @@
+import { describeUiAppCompositionTests } from '@cellix/archunit-tests/ui-app';
+
+describeUiAppCompositionTests({
+	appRoot: 'src',
+	requiredProviders: ['React.StrictMode', 'ThemeProvider', 'ConfigProvider', 'AntdApp', 'HelmetProvider', 'BrowserRouter', 'AuthProvider'],
+});

apps/ui-community/vitest.arch.config.ts

@@ -0,0 +1,3 @@
+import { archConfig } from '@cellix/config-vitest';
+
+export default archConfig;

apps/ui-staff/package.json

@@ -14,6 +14,7 @@
 		"start": "vite",
 		"preview": "vite preview",
 		"test": "vitest run --silent --reporter=dot",
+		"test:arch": "vitest run --config vitest.arch.config.ts",
 		"test:coverage": "vitest run --coverage --silent --reporter=dot",
 		"test:watch": "vitest"
 	},
@@ -39,6 +40,7 @@
 		"react-router-dom": "catalog:"
 	},
 	"devDependencies": {
+		"@cellix/archunit-tests": "workspace:*",
 		"@cellix/config-typescript": "workspace:*",
 		"@cellix/config-vitest": "workspace:*",
 		"@cellix/local-dev": "workspace:*",

apps/ui-staff/src/archunit-tests/ui-app-composition.test.ts

@@ -0,0 +1,6 @@
+import { describeUiAppCompositionTests } from '@cellix/archunit-tests/ui-app';
+
+describeUiAppCompositionTests({
+	appRoot: 'src',
+	requiredProviders: ['React.StrictMode', 'ThemeProvider', 'ConfigProvider', 'AntdApp', 'HelmetProvider', 'BrowserRouter', 'AuthProvider'],
+});

apps/ui-staff/vitest.arch.config.ts

@@ -0,0 +1,3 @@
+import { archConfig } from '@cellix/config-vitest';
+
+export default archConfig;

packages/cellix/archunit-tests/manifest.md

@@ -0,0 +1,55 @@
+# @cellix/archunit-tests package manifest
+
+## Purpose
+
+Provide reusable architectural fitness checks that Cellix applications and libraries can register in their own Vitest suites. The package turns framework composition and organization conventions into executable, consumer-owned contracts.
+
+## Scope
+
+The package inspects TypeScript project source and registers Vitest architecture suites. It covers general framework composition, infrastructure initialization, package-layer conventions, and configurable source organization.
+
+## Public API shape
+
+Each focused export module exposes configuration types, asynchronous checkers that return all discovered violations, and `describe...Tests` helpers that register the checker with Vitest.
+
+## Core concepts
+
+- A checker reports violations without loading consumer runtime modules.
+- A suite helper lets each consumer own and run its architecture contract.
+- UI composition checks require configured providers to occur on the rendered component path to `App` and missing-root guards to terminate the invalid path.
+- Configuration makes project paths and providers explicit, while Serenity bounded contexts are discovered from the consumer's standard context directory instead of embedding OCom-specific names in reusable rules.
+
+## Intended consumers
+
+- Cellix-based API and UI application entrypoints
+- Cellix-based Serenity/Cucumber acceptance and end-to-end suites
+- Cellix library packages that opt into the existing domain, persistence, GraphQL, application-service, frontend, or general conventions
+
+## Package boundaries
+
+- Public modules expose configuration types, violation-returning checkers, and Vitest suite registration helpers.
+- Checks inspect consumer-owned source trees and do not import or execute consumer runtime code.
+- Application-specific paths and bounded-context names are supplied by consumers.
+
+## Non-goals
+
+- Owning OCom-specific business rules or package names
+- Generating application code
+- Replacing behavioral, acceptance, or end-to-end tests
+- Enforcing one fixed monorepo topology where a configurable project path is sufficient
+
+## Dependencies / relationships
+
+The package depends on Node filesystem APIs, Vitest for suite registration, and ArchUnit for established dependency checks. Consumer packages depend on a focused package subpath and provide only their own source paths and conventions.
+
+## Testing strategy
+
+Public contract tests exercise success and violation cases through module entrypoints. Real API, UI, acceptance, and E2E packages then register the reusable suites as downstream architecture tests.
+
+## Documentation obligations
+
+Every new public module must be represented in this manifest and the consumer README. Public functions require parameter, return, and usage documentation at their declaration.
+
+## Release-readiness standards
+
+The package build, full package test suite, and representative downstream consumer suites must pass. Additive exports must remain narrowly scoped; removals or behavior changes require downstream impact review and explicit migration guidance.

packages/cellix/archunit-tests/package.json

@@ -39,6 +39,18 @@
 		"./general": {
 			"types": "./dist/src/general.d.ts",
 			"default": "./dist/src/general.js"
+		},
+		"./api": {
+			"types": "./dist/src/api.d.ts",
+			"default": "./dist/src/api.js"
+		},
+		"./ui-app": {
+			"types": "./dist/src/ui-app.d.ts",
+			"default": "./dist/src/ui-app.js"
+		},
+		"./serenity": {
+			"types": "./dist/src/serenity.d.ts",
+			"default": "./dist/src/serenity.js"
 		}
 	},
 	"scripts": {

packages/cellix/archunit-tests/readme.md

@@ -15,6 +15,49 @@ Current rules in this package include:
 - TypeScript compiler output conventions for `packages/cellix/*`
 - circular dependency checks across Cellix package source graphs
 - framework boundary checks, such as `ui-core` not depending on OCom UI code or app code
+- API startup composition through infrastructure, context, application services, handlers, and startup, including service initialization during Azure `appStart`
+- UI application bootstrap composition, including terminating missing-root validation, configured providers on the rendered path to `App`, and React Router
+- Serenity/Cucumber managed-world initialization, concrete finalized server infrastructure, lifecycle cleanup, context loaders, and Screenplay delegation
+
+## Application Composition
+
+Register the API rule from the API package itself:
+
+```typescript
+import { describeApiCompositionTests } from '@cellix/archunit-tests/api';
+
+describeApiCompositionTests({ apiIndexPath: 'src/index.ts' });
+```
+
+UI applications configure the providers their bootstrap is expected to compose around the rendered `App`. Providers may be nested through local wrapper components, but rendering one elsewhere does not satisfy the contract:
+
+```typescript
+import { describeUiAppCompositionTests } from '@cellix/archunit-tests/ui-app';
+
+describeUiAppCompositionTests({
+	appRoot: 'src',
+	requiredProviders: ['ThemeProvider', 'BrowserRouter', 'AuthProvider'],
+});
+```
+
+## Serenity Suites
+
+Each acceptance or E2E package points the convention at its source root. Contexts are discovered automatically from the immediate directories under `src/contexts`. Infrastructure-backed suites can additionally require scenario cleanup and suite shutdown:
+
+```typescript
+import { describeSerenitySuiteConventionTests } from '@cellix/archunit-tests/serenity';
+
+describeSerenitySuiteConventionTests({
+	suiteRoot: 'src',
+	requireManagedCleanup: true,
+});
+```
+
+The Serenity convention requires a managed world and lifecycle, a central context loader, context-local `*.steps.ts(x)` files, and steps that delegate through context-local Tasks, Interactions, or Questions. Suites that require managed cleanup must also export finalized `ApiInfrastructure` or `E2EInfrastructure` with at least one server; E2E infrastructure must include a UI portal.
+
+## Verifying the Architecture Tests
+
+The package includes intentionally incomplete portable projects under `src/fixtures/architecture-stubs/`. The package's normal architecture suite points each checker at its stub and asserts that the expected violations are reported. These test-of-the-tests run automatically through `test:arch`; no separate stub command or test area is required.
 
 ## What It Does Not Own
 

packages/cellix/archunit-tests/src/api.ts

@@ -0,0 +1,3 @@
+export type { ApiCompositionConfig } from './checks/api-composition.js';
+export { checkApiComposition } from './checks/api-composition.js';
+export { describeApiCompositionTests } from './test-suites/api-composition.js';