@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-assist/tests/test_dyslexia.py

@@ -0,0 +1,337 @@
+"""Tests for dyslexia profile.
+
+Verifies:
+- Parentheticals removed
+- Visual references removed
+- Symbolic emphasis removed
+- Abbreviations expanded
+- Max 5 steps
+- Step numbering with "Step N:" prefix
+- Confidence preserved
+- Commands from allowlist only
+"""
+
+import pytest
+
+from a11y_assist.profiles.dyslexia import (
+    _expand_abbreviations,
+    _normalize_step,
+    _remove_parentheticals,
+    _remove_symbolic_emphasis,
+    _remove_visual_refs,
+    apply_dyslexia,
+)
+from a11y_assist.profiles.dyslexia_render import render_dyslexia
+from a11y_assist.render import AssistResult
+
+
+# Unit tests for helper functions
+
+
+def test_remove_parentheticals():
+    """Should remove parenthetical content."""
+    assert _remove_parentheticals("Check config (optional)") == "Check config"
+    assert _remove_parentheticals("Run command [see docs]") == "Run command"
+    assert _remove_parentheticals("No parens here") == "No parens here"
+
+
+def test_remove_visual_refs():
+    """Should remove visual navigation references."""
+    assert _remove_visual_refs("See above for details") == "for details"
+    assert _remove_visual_refs("Check below") == "Check"
+    assert _remove_visual_refs("Click the left arrow") == "Click the"
+    assert _remove_visual_refs("No visual refs") == "No visual refs"
+
+
+def test_remove_symbolic_emphasis():
+    """Should remove symbolic emphasis characters."""
+    assert _remove_symbolic_emphasis("*important*") == "important"
+    assert _remove_symbolic_emphasis("_underlined_") == "underlined"
+    assert _remove_symbolic_emphasis("Step → Next") == "Step  Next"
+    assert _remove_symbolic_emphasis("No symbols") == "No symbols"
+
+
+def test_expand_abbreviations():
+    """Should expand abbreviations once."""
+    assert "command line" in _expand_abbreviations("Use the CLI tool")
+    assert "I D" in _expand_abbreviations("Check the ID field")
+    assert "J S O N" in _expand_abbreviations("Parse the JSON file")
+    assert "A P I" in _expand_abbreviations("Call the API")
+    assert "S F T P" in _expand_abbreviations("Upload via SFTP")
+
+
+def test_normalize_step_removes_parentheticals():
+    """Step normalization should remove parentheticals."""
+    result = _normalize_step("Run the check (optional)")
+    assert "(" not in result
+    assert ")" not in result
+
+
+def test_normalize_step_removes_visual_refs():
+    """Step normalization should remove visual references."""
+    result = _normalize_step("See above for more info")
+    assert "above" not in result
+
+
+def test_normalize_step_truncates_long_text():
+    """Step normalization should truncate to 110 chars."""
+    long_text = "A" * 150
+    result = _normalize_step(long_text)
+    assert len(result) <= 110
+    assert result.endswith("...")
+
+
+# Tests for apply_dyslexia transform
+
+
+@pytest.fixture
+def base_result() -> AssistResult:
+    """Base result with various elements to transform."""
+    return AssistResult(
+        anchored_id="TEST.ERROR.001",
+        confidence="High",
+        safest_next_step="Check the CLI config (see docs above).",
+        plan=[
+            "Step 1: Verify the JSON file (optional).",
+            "Step 2: Run the API check → next step.",
+            "Step 3: See below for SFTP details.",
+            "Step 4: Final check.",
+            "Step 5: Done.",
+            "Step 6: Extra step (should be truncated).",
+        ],
+        next_safe_commands=["cmd --dry-run", "cmd2 --check"],
+        notes=["Note with *emphasis* and (parenthetical).", "Second note."],
+    )
+
+
+def test_apply_dyslexia_removes_parentheticals(base_result: AssistResult):
+    """Dyslexia transform should remove parentheticals."""
+    result = apply_dyslexia(base_result)
+    assert "(" not in result.safest_next_step
+    assert ")" not in result.safest_next_step
+    for step in result.plan:
+        assert "(" not in step
+        assert ")" not in step
+
+
+def test_apply_dyslexia_removes_visual_refs(base_result: AssistResult):
+    """Dyslexia transform should remove visual references."""
+    result = apply_dyslexia(base_result)
+    assert "above" not in result.safest_next_step.lower()
+    for step in result.plan:
+        assert "below" not in step.lower()
+
+
+def test_apply_dyslexia_removes_symbolic_emphasis(base_result: AssistResult):
+    """Dyslexia transform should remove symbolic emphasis."""
+    result = apply_dyslexia(base_result)
+    for note in result.notes:
+        assert "*" not in note
+
+
+def test_apply_dyslexia_expands_abbreviations(base_result: AssistResult):
+    """Dyslexia transform should expand abbreviations."""
+    result = apply_dyslexia(base_result)
+    # CLI expanded in safest_next_step
+    assert "command line" in result.safest_next_step.lower()
+
+
+def test_apply_dyslexia_max_5_steps(base_result: AssistResult):
+    """Dyslexia transform should limit to 5 steps."""
+    result = apply_dyslexia(base_result)
+    assert len(result.plan) <= 5
+
+
+def test_apply_dyslexia_max_2_notes(base_result: AssistResult):
+    """Dyslexia transform should limit to 2 notes."""
+    result = apply_dyslexia(base_result)
+    assert len(result.notes) <= 2
+
+
+def test_apply_dyslexia_preserves_confidence(base_result: AssistResult):
+    """Dyslexia transform should preserve confidence."""
+    result = apply_dyslexia(base_result)
+    assert result.confidence == base_result.confidence
+
+
+def test_apply_dyslexia_preserves_id(base_result: AssistResult):
+    """Dyslexia transform should preserve anchored ID."""
+    result = apply_dyslexia(base_result)
+    assert result.anchored_id == base_result.anchored_id
+
+
+def test_apply_dyslexia_preserves_commands(base_result: AssistResult):
+    """Dyslexia transform should preserve safe commands."""
+    result = apply_dyslexia(base_result)
+    assert result.next_safe_commands == base_result.next_safe_commands[:3]
+
+
+# Tests for render_dyslexia
+
+
+def test_render_dyslexia_header():
+    """Render should include dyslexia header."""
+    result = AssistResult(
+        anchored_id="TEST.001",
+        confidence="High",
+        safest_next_step="Check config.",
+        plan=["Step 1."],
+        next_safe_commands=[],
+        notes=[],
+    )
+    output = render_dyslexia(result)
+    assert "ASSIST (Dyslexia):" in output
+
+
+def test_render_dyslexia_explicit_labels():
+    """Render should use explicit labels."""
+    result = AssistResult(
+        anchored_id="TEST.001",
+        confidence="High",
+        safest_next_step="Check config.",
+        plan=["Step 1.", "Step 2."],
+        next_safe_commands=["cmd --dry-run"],
+        notes=["A note."],
+    )
+    output = render_dyslexia(result)
+    assert "Anchored ID:" in output
+    assert "Confidence:" in output
+    assert "Safest next step:" in output
+    assert "Plan:" in output
+    assert "Next safe command:" in output
+    assert "Notes:" in output
+
+
+def test_render_dyslexia_step_numbering():
+    """Render should use 'Step N:' prefix."""
+    result = AssistResult(
+        anchored_id="TEST.001",
+        confidence="High",
+        safest_next_step="Check config.",
+        plan=["First step.", "Second step.", "Third step."],
+        next_safe_commands=[],
+        notes=[],
+    )
+    output = render_dyslexia(result)
+    assert "- Step 1:" in output
+    assert "- Step 2:" in output
+    assert "- Step 3:" in output
+
+
+def test_render_dyslexia_no_command_on_low():
+    """Render should not show command on Low confidence."""
+    result = AssistResult(
+        anchored_id=None,
+        confidence="Low",
+        safest_next_step="Check config.",
+        plan=["Step 1."],
+        next_safe_commands=["cmd --dry-run"],
+        notes=[],
+    )
+    output = render_dyslexia(result)
+    assert "Next safe command:" not in output
+
+
+def test_render_dyslexia_shows_command_on_high():
+    """Render should show command on High confidence."""
+    result = AssistResult(
+        anchored_id="TEST.001",
+        confidence="High",
+        safest_next_step="Check config.",
+        plan=["Step 1."],
+        next_safe_commands=["cmd --dry-run"],
+        notes=[],
+    )
+    output = render_dyslexia(result)
+    assert "Next safe command:" in output
+    assert "cmd --dry-run" in output
+
+
+def test_render_dyslexia_vertical_spacing():
+    """Render should have blank lines between sections."""
+    result = AssistResult(
+        anchored_id="TEST.001",
+        confidence="High",
+        safest_next_step="Check config.",
+        plan=["Step 1."],
+        next_safe_commands=[],
+        notes=[],
+    )
+    output = render_dyslexia(result)
+    # Should have multiple blank lines for visual separation
+    assert "\n\n" in output
+
+
+# Integration tests
+
+
+def test_dyslexia_full_pipeline():
+    """Full pipeline test for dyslexia profile."""
+    base = AssistResult(
+        anchored_id="DEPLOY.CONFIG.MISSING",
+        confidence="High",
+        safest_next_step="Check the CLI configuration file (located in /etc/app).",
+        plan=[
+            "Verify the JSON config exists (optional step).",
+            "Run: deploy check --dry-run",
+            "See above for API endpoint details.",
+        ],
+        next_safe_commands=["deploy check --dry-run"],
+        notes=["*Important*: This is critical."],
+    )
+
+    transformed = apply_dyslexia(base)
+    output = render_dyslexia(transformed)
+
+    # Header present
+    assert "ASSIST (Dyslexia):" in output
+
+    # ID preserved
+    assert "DEPLOY.CONFIG.MISSING" in output
+
+    # Confidence preserved
+    assert "Confidence: High" in output
+
+    # No parentheticals in content (header "(Dyslexia)" is ok)
+    # Check that plan steps and notes don't have parentheticals
+    for step in transformed.plan:
+        assert "(" not in step
+        assert ")" not in step
+    assert "(" not in transformed.safest_next_step
+    assert ")" not in transformed.safest_next_step
+
+    # No visual refs
+    assert "above" not in output.lower()
+
+    # No symbolic emphasis
+    assert "*" not in output
+
+    # Step numbering
+    assert "- Step 1:" in output
+
+    # Command shown
+    assert "deploy check --dry-run" in output
+
+
+def test_dyslexia_low_confidence():
+    """Dyslexia profile with Low confidence."""
+    base = AssistResult(
+        anchored_id=None,
+        confidence="Low",
+        safest_next_step="Review the output.",
+        plan=["Step 1.", "Step 2."],
+        next_safe_commands=["cmd --dry-run"],
+        notes=["No ID found."],
+    )
+
+    transformed = apply_dyslexia(base)
+    output = render_dyslexia(transformed)
+
+    # Confidence preserved
+    assert "Confidence: Low" in output
+
+    # No command on Low confidence
+    assert "Next safe command:" not in output
+
+    # ID shows as none
+    assert "Anchored ID: none" in output

package/src/a11y-assist/tests/test_explain.py

@@ -0,0 +1,74 @@
+"""Tests for the explain command (cli.error.v0.1 JSON)."""
+
+from pathlib import Path
+
+import pytest
+
+from a11y_assist.from_cli_error import (
+    CliErrorValidationError,
+    assist_from_cli_error,
+    load_cli_error,
+)
+
+FIX = Path(__file__).parent / "fixtures"
+
+
+class TestLoadCliError:
+    """Tests for loading cli.error.v0.1 JSON files."""
+
+    def test_load_valid_array_format(self):
+        """Load valid JSON with array format for what/why/fix."""
+        obj = load_cli_error(str(FIX / "cli_error_good.json"))
+        assert obj["code"] == "PAY001"
+        assert obj["id"] == "PAY.EXPORT.SFTP.AUTH"
+
+    def test_load_valid_string_format(self):
+        """Load valid JSON with string format for what/why/fix."""
+        obj = load_cli_error(str(FIX / "cli_error_string_format.json"))
+        assert obj["code"] == "CFG001"
+        assert obj["what"] == "Configuration file missing"
+
+    def test_load_missing_code_raises(self):
+        """Missing code field raises validation error."""
+        with pytest.raises(CliErrorValidationError) as exc_info:
+            load_cli_error(str(FIX / "cli_error_missing_id.json"))
+        assert "code" in str(exc_info.value.errors)
+
+
+class TestAssistFromCliError:
+    """Tests for generating assist from cli.error.v0.1."""
+
+    def test_explain_from_valid_cli_error(self):
+        """Generate high-confidence assist from valid JSON."""
+        obj = load_cli_error(str(FIX / "cli_error_good.json"))
+        res = assist_from_cli_error(obj)
+        assert res.confidence == "High"
+        assert res.anchored_id == "PAY.EXPORT.SFTP.AUTH"
+        assert res.plan
+        assert len(res.plan) >= 1
+
+    def test_explain_uses_code_as_fallback_id(self):
+        """Use code field as fallback when id is not present."""
+        obj = load_cli_error(str(FIX / "cli_error_string_format.json"))
+        res = assist_from_cli_error(obj)
+        assert res.anchored_id == "CFG001"
+
+    def test_plan_contains_fix_steps(self):
+        """Plan is built from fix field."""
+        obj = load_cli_error(str(FIX / "cli_error_good.json"))
+        res = assist_from_cli_error(obj)
+        assert "Verify credentials." in res.plan
+
+    def test_safe_commands_extracted(self):
+        """SAFE commands extracted from fix with --dry-run."""
+        obj = load_cli_error(str(FIX / "cli_error_good.json"))
+        res = assist_from_cli_error(obj)
+        # Should find the dry-run command
+        dry_run_cmds = [c for c in res.next_safe_commands if "--dry-run" in c]
+        assert len(dry_run_cmds) >= 1
+
+    def test_notes_include_original_title(self):
+        """Notes include the original title."""
+        obj = load_cli_error(str(FIX / "cli_error_good.json"))
+        res = assist_from_cli_error(obj)
+        assert any("Payment export failed" in n for n in res.notes)

package/src/a11y-assist/tests/test_golden.py

@@ -0,0 +1,127 @@
+"""Golden fixture tests for deterministic output verification.
+
+Golden tests ensure that profile outputs remain stable and any changes
+are explicit and reviewable. These are the memory of the engine.
+
+Rules for updating golden files:
+1. The change must be intentional
+2. ENGINE.md must still hold
+3. Guard invariants must still pass
+4. Commit message must explain why output changed
+"""
+
+from pathlib import Path
+
+import pytest
+
+from a11y_assist.from_cli_error import load_cli_error, assist_from_cli_error
+from a11y_assist.profiles import (
+    apply_cognitive_load,
+    apply_dyslexia,
+    apply_plain_language,
+    apply_screen_reader,
+    render_cognitive_load,
+    render_dyslexia,
+    render_plain_language,
+    render_screen_reader,
+)
+from a11y_assist.render import render_assist
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+BASE_INPUTS = FIXTURES_DIR / "base_inputs"
+EXPECTED = FIXTURES_DIR / "expected"
+
+
+def load_fixture(path: Path) -> str:
+    """Load a fixture file as string."""
+    return path.read_text(encoding="utf-8")
+
+
+def load_json_input(name: str):
+    """Load and parse a JSON input fixture."""
+    return load_cli_error(str(BASE_INPUTS / name))
+
+
+class TestGoldenHighConfidence:
+    """Golden tests for high-confidence cli.error.v0.1 input."""
+
+    @pytest.fixture
+    def base_result(self):
+        """Load base AssistResult from cli_error_high.json."""
+        obj = load_json_input("cli_error_high.json")
+        return assist_from_cli_error(obj)
+
+    def test_lowvision_golden(self, base_result):
+        """Lowvision profile output must match golden fixture."""
+        # Lowvision is the default, no transform needed
+        rendered = render_assist(base_result)
+        expected = load_fixture(EXPECTED / "lowvision_high.txt")
+        assert rendered.strip() == expected.strip()
+
+    def test_cognitive_load_golden(self, base_result):
+        """Cognitive-load profile output must match golden fixture."""
+        transformed = apply_cognitive_load(base_result)
+        rendered = render_cognitive_load(transformed)
+        expected = load_fixture(EXPECTED / "cognitive_load_high.txt")
+        assert rendered.strip() == expected.strip()
+
+    def test_screen_reader_golden(self, base_result):
+        """Screen-reader profile output must match golden fixture."""
+        transformed = apply_screen_reader(base_result)
+        rendered = render_screen_reader(transformed)
+        expected = load_fixture(EXPECTED / "screen_reader_high.txt")
+        assert rendered.strip() == expected.strip()
+
+    def test_dyslexia_golden(self, base_result):
+        """Dyslexia profile output must match golden fixture."""
+        transformed = apply_dyslexia(base_result)
+        rendered = render_dyslexia(transformed)
+        expected = load_fixture(EXPECTED / "dyslexia_high.txt")
+        assert rendered.strip() == expected.strip()
+
+    def test_plain_language_golden(self, base_result):
+        """Plain-language profile output must match golden fixture."""
+        transformed = apply_plain_language(base_result)
+        rendered = render_plain_language(transformed)
+        expected = load_fixture(EXPECTED / "plain_language_high.txt")
+        assert rendered.strip() == expected.strip()
+
+
+class TestGoldenDeterminism:
+    """Verify determinism: same input always produces same output."""
+
+    def test_multiple_runs_identical(self):
+        """Running the same input multiple times must produce identical output."""
+        obj = load_json_input("cli_error_high.json")
+
+        outputs = []
+        for _ in range(5):
+            result = assist_from_cli_error(obj)
+            transformed = apply_cognitive_load(result)
+            rendered = render_cognitive_load(transformed)
+            outputs.append(rendered)
+
+        # All outputs must be identical
+        assert len(set(outputs)) == 1, "Output must be deterministic"
+
+    def test_all_profiles_deterministic(self):
+        """All profiles must produce deterministic output."""
+        obj = load_json_input("cli_error_high.json")
+
+        profiles = [
+            (lambda r: r, render_assist),
+            (apply_cognitive_load, render_cognitive_load),
+            (apply_screen_reader, render_screen_reader),
+            (apply_dyslexia, render_dyslexia),
+            (apply_plain_language, render_plain_language),
+        ]
+
+        for transform, renderer in profiles:
+            outputs = []
+            for _ in range(3):
+                result = assist_from_cli_error(obj)
+                transformed = transform(result)
+                rendered = renderer(transformed)
+                outputs.append(rendered)
+
+            assert len(set(outputs)) == 1, f"Profile must be deterministic"