Weekly A2UI Compliance Report (2026-07-28)

# **A2UI Weekly Compliance & Test Quality Audit Report**

This combined report compiles specifications compliance, documentation synchronization, and test quality audits for the A2UI monorepo codebases.

---

## **## Summary**

An extensive static and structural audit has been conducted across all eight platform codebases, documentation suites, and test frameworks in the A2UI repository.

- **Blueprint Compliance (🟡 Out of Date - Metadata Tracking)**: Physically, all codebases are fully synchronized with the latest module specifications (including the recent spec alignment for the `Slider` component's `step` property under commit `5cd29ce`). However, all codebase blueprints currently have their pinned commit hash set to `null`, triggering a yellow compliance status in automated audits.
- **Documentation Synchronization (⚠️ Drift Detected)**: High fidelity overall, but a critical documentation bug was identified in the Angular Renderer README where an incorrect injection token name (`A2UI_RENDER_CONFIG` instead of `A2UI_RENDERER_CONFIG`) is recommended for setup.
- **Test Quality & Coverage (⚠️ Unit Test Gap)**: High assertion strength and excellent use of modern testing frameworks (Preact signals, Jasmine spies, visual pixel-parity, and Swift Testing with `#expect`). However, a major unit testing coverage gap exists under `@a2ui/web_core` where basic catalog component schema validations are only unit-tested for `Image` and `Slider`.

---

## **## Recommendations**

Listed in order of priority:

1. 🔴 **HIGH PRIORITY - Fix Angular README Drift**:
Update `renderers/angular/README.md#L31` to reference `A2UI_RENDERER_CONFIG` instead of `A2UI_RENDER_CONFIG` to prevent copy-paste compiler errors for integration developers.
2. 🟡 **MEDIUM PRIORITY - Baseline Codebase Blueprints**:
Update the `module_blueprint_commit` property in all codebase blueprint markdown files under `blueprints/codebases/` from `null` to the current HEAD commit (`5cd29ceb729a4b95a3c0f652ff255f54ce163d8b`) to establish a clear baseline and transition automated tracking to "Up to Date".
3. 🟡 **MEDIUM PRIORITY - Expand Web Core Schema Unit Tests**:
Extend `@a2ui/web_core` unit tests (`renderers/web_core/src/v0_9/basic_catalog/components/basic_components.test.ts`) to validate schemas for the remaining 14 basic catalog components (such as `Button`, `Text`, `ChoicePicker`, etc.) to prevent future schema regression drifts.
4. 🟢 **LOW PRIORITY - Future-proof React Defaults**:
In a future major release of `@a2ui/react` (v1.0), consider updating the default export to point directly to the recommended `v0_9` implementation rather than `v0_8` legacy routes.

---

## **## Codebase Blueprint Compliance Audit**

The automated blueprint compliance checker script was executed to evaluate the tracking metadata for each platform codebase against the module blueprints.

### **Summary Status**

| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |
|---|---|---|---|---|---|
| `agent_sdks/python/a2ui_agent` | `a2ui_inference` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |
| `agent_sdks/python/a2ui_core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |
| `renderers/angular` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |
| `renderers/flutter` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |
| `renderers/lit` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |
| `renderers/react` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |
| `renderers/web_core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |
| `swift/core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `5cd29ceb` |

### **Manual Verification & Metadata Insights**

- **Implementation Parity (Step 2.1)**: Statically verifying the codebase implementations confirms that all folders are physically synchronized with the latest `v0.9` module specifications. The recent update from commit `5cd29ce` (removing `step` from `SliderApi` and updating the Angular slider renderer) is already correctly integrated. The "Out of Date" state is solely metadata-driven due to unbaselined `null` values.
- **Claimed Feature Verification (Step 2.2)**: For all 8 codebase blueprints, `implemented_features: []` is currently an empty list. No features are currently claimed in the metadata, meaning no discrepancies exist between claimed and implemented features.
- **Optional Features Checklist (Step 2.3)**: No optional features are currently registered, and custom extensions correspond correctly with modular requirements.

---

## **## Code & Documentation Sync Audit**

A comprehensive cross-reference audit was completed to map documentation resources and readme files against concrete API classes, package structures, and command specifications.

### **Audited Documentation Directories**

| Directory / Package | Primary Documentation | Build/Config Manifest | Status |
|---|---|---|---|
| `agent_sdks/python/a2ui_agent` | `README.md` | `pyproject.toml` | Symmetrical |
| `agent_sdks/python/a2ui_core` | `README.md` | `pyproject.toml` | Symmetrical |
| `renderers/angular` | `README.md` | `package.json` | ❌ Drift Detected |
| `renderers/react` | `README.md` | `package.json` | Symmetrical |
| `renderers/lit` | `README.md` | `package.json` | Symmetrical |
| `renderers/web_core` | `README.md` | `package.json` | Symmetrical |
| `swift/core` | `AGENTS.md`, `CODING_STANDARDS.md` | `Package.swift` | Symmetrical |

### **Audit Details & Synchronization Drifts**

1. **Angular Injection Token Misnaming (Critical Readme Bug)**:
- **Location**: `renderers/angular/README.md` on line 31.
- **Issue**: Tells developers to configure the renderer in `app.config.ts` using the `A2UI_RENDER_CONFIG` token.
- **Correction**: The actual exported and integrated injection token in the Angular library is `A2UI_RENDERER_CONFIG` (as seen on lines 25, 35, and 40). This discrepancy causes compilation failures for developers copying setup configurations.
2. **Command Consistency**:
- Python codebases cleanly coordinate dependencies and development tasks via `uv` workspace commands from the root workspace structure.
- Node packages correctly run commands like `yarn build` and `yarn test` mapped through `wireit` scripts.
3. **API & Docstring Correspondence**:
- Public entry points across `DataModel`, `MessageProcessor`, and `GenericBinder` match their docstrings, parameter types, and throwing behaviors perfectly with no structural drift.

---

## **## Test Quality & Assertions Audit**

All test directories and test configurations across the eight codebases were audited statically for assertion completeness, coverage strength, and structural realism.

### **Platform Test Suites Audit**

| Suite Location | Framework | Assertion Quality | Testing Realism | Status |
|---|---|---|---|---|
| `agent_sdks/python/a2ui_agent/tests` | pytest | Strong (Detailed) | Strong (Context mocks) | Passed |
| `agent_sdks/python/a2ui_core/tests` | pytest | Strong (Detailed) | Strong (Context mocks) | Passed |
| `renderers/angular/src/v0_9/.../specs` | Jasmine | Strong (Spies/Elements) | High (Signal binding) | Passed |
| `renderers/react/tests` | Vitest / RTL | Strong (Visual/E2E) | High (Parity screenshots) | Passed |
| `renderers/lit/tests` | Vitest | Strong (Visual/E2E) | High (Parity screenshots) | Passed |
| `renderers/web_core/src/v0_9/...` | Node Test | Strong (Assert module) | Symmetrical (Mock data) | ⚠️ Coverage Gap |
| `swift/core/Tests` | Swift-Testing | Modern (`#expect`) | Symmetrical (Thread-safe) | Passed |

### **Audit Findings**

- **Assertion Quality**: Highly precise and clean. The codebases avoid generic truthy/null checks for main verification steps, favoring strict equality (`expect(input.value).toBe('50')` and `#expect(result.stringValue == "Hello, World!")`). Spies are correctly verifying exact argument structures.
- **Coverage Gap (Web Core basic component schemas)**:
- **Location**: `renderers/web_core/src/v0_9/basic_catalog/components/basic_components.test.ts`.
- **Issue**: The schema validation unit test suite only asserts validation schemas for `ImageApi` and `SliderApi`. The other 14 components defined in `basic_components.ts` (including `Button`, `Text`, `List`, `Card`, etc.) have zero schema-specific unit tests under `web_core`, relying solely on downstream rendering integration tests.
- **Mocking Realism**: Outstanding. The visual parity suites across React and Lit utilize automated E2E visual comparisons to ensure pixel-perfect parity, which represents the highest echelon of assertion realism.

Issue liệt kê ba tác vụ cụ thể: cập nhật Angular README tại `renderers/angular/README.md#L31`, cập nhật các hash commit của blueprint trong `blueprints/codebases/`, và mở rộng unit test trong `renderers/web_core/src/v0_9/basic_catalog/components/basic_components.test.ts`. Trước tiên, hãy tìm các tệp này trong repository. Để cập nhật blueprint, hãy tìm commit HEAD hiện tại (`5cd29ceb729a4b95a3c0f652ff255f54ce163d8b`) từ lịch sử git. Đối với các test, hãy kiểm tra `basic_components.ts` để xác định 14 component còn thiếu. Xác minh các thay đổi bằng cách chạy các lệnh test liên quan (chẳng hạn như `yarn test` trong thư mục web_core).

Do mô hình lập chỉ mục viết ra từ nội dung của issue.