grantiva/doctor

Swift Assist: Doctor

Walk every screen of the running iOS app using computer use, inspect the view hierarchy via grantiva runner dump-hierarchy, and produce a report of interactive elements missing .accessibilityIdentifier().

Usage

/swift-assist:doctor
/swift-assist:doctor --screen=LoginView
/swift-assist:doctor --fix
/swift-assist:doctor --json

Command Options

• --screen=<ViewName>: Only audit a specific screen instead of the full app
• --fix: Automatically run /swift-assist:add-identifiers after the audit completes
• --json: Output findings as JSON for tooling integration

Prerequisites

1. The app must be running in a simulator (run /swift-assist:init first)
2. The Grantiva runner session must be active:

   grantiva runner start
   

3. Computer use must be available for visual navigation

Naming Convention

All suggested accessibility identifiers follow this pattern:

<screen>-<elementType>-<descriptor>

Where:

• screen: Inferred from the SwiftUI view struct name (lowercased, hyphenated). e.g., LoginView becomes login
• elementType: The UI element type: button, textfield, securefield, toggle, slider, picker, image, tab, link, label
• descriptor: A short, descriptive name for what the element does, derived from the element's label, text, or purpose

Examples:

login-button-continue
login-textfield-email
login-securefield-password
onboarding-image-hero-banner
settings-toggle-notifications
deeplinks-link-caching-demo
edit-landmark-button-done
grantiva-textfield-user-id

What This Command Does

Phase 1: Source Code Pre-Scan

Before walking the app, scan the Swift source to build a map of views and their elements:

1. Find all SwiftUI view files:

   grep -rl "struct.*:.*View" --include="*.swift" .
   

2. For each view file, catalog interactive elements:

   • Button, TextField, SecureField, Toggle, Slider, Picker, DatePicker
   • NavigationLink, Image (when interactive), .onTapGesture
   • TabView tabs, Link

3. Note which elements already have .accessibilityIdentifier() applied

4. Build a lookup table: ViewName -> [element, hasIdentifier, suggestedId]

Phase 2: Walk the App with Computer Use

This phase requires computer use (MCP browser tools targeting the simulator).

Navigation Strategy

1. Take a screenshot of the current screen
2. Dump the hierarchy - run grantiva runner dump-hierarchy to get the live accessibility tree
3. Identify the current view by matching visible elements to the source code scan
4. Record findings - compare live hierarchy against source scan, noting:
   • Elements with no accessibility identifier
   • Elements with generic/unhelpful identifiers
   • Elements that are interactive but not accessible
5. Navigate to the next screen:
   • If TabView exists, visit each tab
   • Follow NavigationLinks and back-navigate
   • Tap buttons that lead to new screens (sheets, modals, pushes)
   • If --screen was specified, navigate only to that screen

Important: Tab Identifiers

Tab bar buttons in SwiftUI do NOT receive the .accessibilityIdentifier() you set on the tab content. The hierarchy shows tab buttons as:

[XCUIElementTypeButton] name="map" label="Landmarks"
[XCUIElementTypeButton] name="heart" label="Favorites"

The name is the SF Symbol, the label is the display text. Test flows should tap tabs by their label text (e.g., tap: "Favorites"), not by a custom identifier. Still add identifiers to tab content for code organization, but note in the report that tabs are tapped by label.

For Each Screen

1. Screenshot the screen
2. Run grantiva runner dump-hierarchy to get the element tree
3. Use grantiva runner dump-hierarchy --format json for programmatic parsing
4. Cross-reference with source code to identify the SwiftUI view struct
5. For each interactive element without an identifier:
   • Determine the screen from the view struct name
   • Determine the elementType from the UI component
   • Determine the descriptor from the element's label, text content, or SF Symbol name
   • Generate the suggested identifier

Phase 3: Generate Report

Produce a structured report:

Accessibility Doctor Report
============================

Scanned: 11 views, 54 interactive elements
Missing identifiers: 54

ContentView (5 missing)
  - Tab "Landmarks"           -> content-tab-landmarks (tap by label)
  - Tab "Favorites"           -> content-tab-favorites (tap by label)
  - Tab "Grantiva"            -> content-tab-grantiva (tap by label)
  - Tab "Feedback"            -> content-tab-feedback (tap by label)
  - Tab "Deep Links"          -> content-tab-deeplinks (tap by label)

LandmarkDetailView (3 missing)
  - NavigationLink (category) -> landmark-detail-link-category
  - NavigationLink "Plan Visit" -> landmark-detail-link-plan-visit
  - Button (favorite)         -> landmark-detail-button-favorite

EditLandmarkView (4 missing)
  - TextField "Name"          -> edit-landmark-textfield-name
  - TextField "Location"      -> edit-landmark-textfield-location
  - Button "Cancel"           -> edit-landmark-button-cancel
  - Button "Done"             -> edit-landmark-button-done

Coverage: 0/54 elements have identifiers (0%)

Phase 4: Save Findings

Save the report to .grantiva/doctor-report.json so that /swift-assist:add-identifiers can consume it.

Phase 5: Optional Auto-Fix

If --fix was specified, immediately invoke /swift-assist:add-identifiers with the saved report.

Important Rules

1. NEVER modify source code in this command (unless --fix is specified, which delegates to /swift-assist:add-identifiers)
2. Always take screenshots as evidence of what was found on each screen
3. If you cannot reach a screen (e.g., requires login or API data), note it as "unreachable" and suggest adding mock services
4. Do not suggest identifiers for non-interactive decorative elements
5. If an element already has a good identifier, do not suggest replacing it
6. The grantiva runner dump-hierarchy output is ground truth - if source scan and live hierarchy disagree, trust the live hierarchy
7. Stop walking after visiting all reachable screens - do not loop infinitely