Weekly A2UI Compliance Report (2026-07-21)

# Weekly A2UI Compliance & Quality Audit Report

## Summary
This report provides a comprehensive, tri-layered audit of the A2UI repository. It checks codebase specification compliance against module blueprints, verifies code-to-documentation synchronization, and evaluates the rigor of test suites across multiple frameworks (Python, React, Lit, Angular, Swift).

Key areas checked:
1. **Blueprint Parity**: Running static parsing scripts to compare pinned commits vs. module blueprints and validating codebase implementation maturity.
2. **Documentation Accuracy**: Verifying README setups, code comment sanity, and checking for deprecated or erroneous command listings.
3. **Test Quality**: Searching for empty/placeholder test suites, assessing assertion strength, and flagging weak patterns (e.g. redundant assertions, null checks on structured payloads).

---

## Recommendations
Below is the prioritized action list to address the discrepancies identified during the audit:

1. **[CRITICAL] Swift Core Implementation & Testing**: Implement the core state machine and validation pipeline in `swift/core/Sources/A2UICore/` to replace the placeholder implementation, and add full test coverage to replace the empty `#expect(Bool(true))` test.
2. **[HIGH] Fix Python SDK Dev Dependencies**: Add `pytest` (and `pytest-cov` / `pyink` if required) to the `dev` dependency-group under `pyproject.toml` for both `agent_sdks/python/a2ui_core` and `agent_sdks/python/a2ui_agent`.
3. **[HIGH] Update Pinned Commits**: Update the `module_blueprint_commit` in the frontmatter of all codebase blueprints from `null` to the latest commit `91b1a13a` once parity is confirmed.
4. **[MEDIUM] Add Swift Core README**: Create a standardized `README.md` under `swift/core` specifying package structure, build commands, and target layouts.
5. **[MEDIUM] Fix Invalid Install Command**: Correct `renderers/web_core/README.md` to use `yarn add @a2ui/web_core` instead of the invalid `yarn install @a2ui/web_core` syntax.
6. **[LOW] Enhance Assertion Strength**:
- In Python tests, replace generic `is not None` assertions on payloads with value-matching assertions.
- In React tests, replace redundant `.toBeDefined()` checks on `screen.getBy...` queries with direct semantic assertions (or omit the redundancy).

---

## Codebase Blueprint Compliance Audit

The blueprint compliance verification tracks the synchronization status of each platform codebase against the language-agnostic 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` | `91b1a13a` |
| `agent_sdks/python/a2ui_core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `91b1a13a` |
| `renderers/angular` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `91b1a13a` |
| `renderers/flutter` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `91b1a13a` |
| `renderers/lit` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `91b1a13a` |
| `renderers/react` | `a2ui_framework_adapter` | 🟡 Out of Date | 1 | `null` | `91b1a13a` |
| `renderers/web_core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `91b1a13a` |
| `swift/core` | `a2ui_core` | 🟡 Out of Date | 1 | `null` | `91b1a13a` |

### Discrepancies & Details by Codebase

1. **Un-baselined/Null Pinned Commits**:
All 8 codebases have their `module_blueprint_commit` set to `null` in their codebase blueprint metadata. Consequently, they are flagged as 1 commit behind the latest module change (`91b1a13a` - "fix: make Getting Started work for Mac OS (#1515)").

2. **Swift Core Blueprint Mismatch (Placeholder Status)**:
While `swift/core` is associated with the `a2ui_core` module blueprint, the actual implementation at `/swift/core/Sources/A2UICore/A2UICore.swift` is only a placeholder stating:
> *This file is intentionally a placeholder; real types will be added in subsequent PRs.*
Thus, `swift/core` currently lacks compliance with the `a2ui_core` specification.

3. **Details by Codebase**:

#### 📦 `agent_sdks/python/a2ui_agent` (🟡 Out of Date)
- **Module**: `a2ui_inference`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

#### 📦 `agent_sdks/python/a2ui_core` (🟡 Out of Date)
- **Module**: `a2ui_core`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

#### 📦 `renderers/angular` (🟡 Out of Date)
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

#### 📦 `renderers/flutter` (🟡 Out of Date)
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

#### 📦 `renderers/lit` (🟡 Out of Date)
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

#### 📦 `renderers/react` (🟡 Out of Date)
- **Module**: `a2ui_framework_adapter`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

#### 📦 `renderers/web_core` (🟡 Out of Date)
- **Module**: `a2ui_core`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

#### 📦 `swift/core` (🟡 Out of Date)
- **Module**: `a2ui_core`
- **Current Pinned Commit**: `null`
- **Latest Module Commit**: `91b1a13a9dca49237cbe2567971340510bb318d7`
- **Reason/Info**: Codebase is behind by 1 commit(s)

```text
91b1a13 fix: make Getting Started work for Mac OS (#1515)
```

---

## Code & Documentation Sync Audit

### Audited Codebases & Directories
The following directories were audited for documentation and command synchronization:
- `agent_sdks/python/a2ui_agent`
- `agent_sdks/python/a2ui_core`
- `renderers/web_core`
- `renderers/react`
- `renderers/angular`
- `renderers/lit`
- `swift/core`

### Key Findings

#### 1. Documentation Drift
- **Missing Core README**: The `swift/core` directory is completely missing its `README.md` file. It contains `AGENTS.md` and `CODING_STANDARDS.md` guides, but fails to provide a general introductory/setup guide for developers.

#### 2. Readme Errors
- **Invalid Yarn Command**: In `renderers/web_core/README.md`, line 30 instructs users to run `yarn install @a2ui/web_core`. In Yarn (specifically Yarn v4 which is configured in the root `package.json`), running `yarn install` with a package name argument is invalid. It should be `yarn add @a2ui/web_core`.
- **Missing Dev Dependencies for Test Execution**:
Both `agent_sdks/python/a2ui_agent/README.md` and `agent_sdks/python/a2ui_core/README.md` direct the user to run unit/conformance tests via:
```bash
uv run pytest
```
However, neither package's `pyproject.toml` file lists `pytest` under their `[dependency-groups] dev` section or main `dependencies`. Running this command directly in a clean virtual environment will fail since `pytest` is not installed or resolved by `uv`.

#### 3. Docstring Mismatches
- Minor comment anomalies were observed in older v0.8 subdirectories where comments or terminology references are not fully updated to v0.9 (e.g. references to direct property binding without signals).

---

## Test Quality & Assertions Audit

### Audited Test Suites
The following test directories were audited for assertion coverage, boundaries, and testing patterns:
- `agent_sdks/python/a2ui_agent/tests/`
- `agent_sdks/python/a2ui_core/tests/`
- `swift/core/Tests/`
- `renderers/react/tests/`
- `renderers/lit/src/`
- `renderers/angular/src/`

### Key Findings

#### 1. Weak Assertions
- **Payload Null/None Checking**: In Python tests (e.g. `agent_sdks/python/a2ui_agent/tests/test_formats.py` lines 88 and 107), test assertions verify structure solely via `assert parsed[0].a2ui_json is not None` instead of doing deep field validation or checking inner properties like components or actions.
- **Redundant `.toBeDefined()` Assertions in React Tests**:
Throughout the React renderer tests (e.g. `renderers/react/tests/v0_9/adapter.test.tsx` and `catalog-components.test.tsx`), assertions of the form `expect(screen.getByText('...')).toBeDefined()` or `expect(screen.getByTestId('...')).toBeDefined()` are used.
In React Testing Library, `screen.getBy...` queries automatically throw an error if the element is not found. Thus, asserting that the result is defined is redundant. These should either be simplified (omitting the assertion completely or using `.toBeInTheDocument()`).

#### 2. Empty / Placeholder Test Suites
- **Empty Swift Core Test Suite**:
The `swift/core/Tests/A2UICoreTests/A2UICoreTests.swift` file contains only a single placeholder test case:
```swift
struct A2UICoreTests {
@Test func placeholderTest() {
#expect(Bool(true))
}
}
```
Because the Swift core itself is currently a placeholder, it has zero behavioral coverage, edge cases, error boundary validation, or interaction testing.

#### 3. Mocking Realism & Scoping
- In complex template and action tests (e.g. nested lists in React), mock action handlers are verified to have been called, but deeper value validation on the returned action payloads (such as verifying correct relative context paths) is occasionally omitted.

Báo cáo liệt kê nhiều codebase và các tệp cụ thể cần cập nhật. Trước tiên, hãy tìm các tệp `pyproject.toml` trong các thư mục SDK Python để thêm các dependency dành cho phát triển của pytest. Kiểm tra dòng 30 trong `renderers/web_core/README.md` để sửa lệnh yarn. Đối với Swift core, hãy kiểm tra `/swift/core/Sources/A2UICore/A2UICore.swift` và tệp kiểm thử của nó để thay thế các placeholder. Mỗi tác vụ yêu cầu xác minh trạng thái hiện tại và thực hiện thay đổi được chỉ định, sau đó chạy các kiểm thử hiện có để đảm bảo không có gì bị hỏng.

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