Weekly A2UI Compliance Report (2026-07-21)

[gspencergoog]

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 (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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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:

  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:

  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.

[polina-c]

As agreed, this has been assigned a P3 priority. Once the current triage queue is cleared,
we will begin reviewing AI-generated issues.