# Com / Example

## Overview

The `com.example` package serves as the root package for a small set of **test fixture** code. Rather than containing production logic, this area of the codebase exists to validate the behavior of a JSP parser — specifically, its handling of `<%@ page %>` directive attributes. The primary concern of this module is exercising and verifying a fix for [BUG-CA-002](bugca002.md), an edge case where attribute ordering within a page directive causes the parser to drop import declarations.

## Sub-module Guide

The `com.example` package contains the following sub-module:

### `com.example.bugca002` — JSP Attribute Order Regression Test

This sub-module tests a parser bug where placing `language=` before `import=` in a JSP page directive causes the import statement to be silently ignored. It contains:

- **`KnownClass`** — a minimal, no-op Java class that serves as the resolution target for the JSP import. It has no fields, no explicit constructors, and a single empty `execute()` method. Its only purpose is to give the parser something to resolve when it processes the import.
- **`BugCa002Language Before Import.jsp`** — a JSP page whose page directive deliberately places `language="java"` before `import="com.example.bugca002.KnownClass"`. The filename intentionally contains a space to test file-handling edge cases as well.

These two files work together as a complete regression test: the JSP declares the import in an attribute order that previously triggered the parser bug, and `KnownClass` provides the class that should have been resolved if the parser had handled the attribute correctly.

## Key Patterns and Architecture

This module follows a **test-fixture architecture** — its components are deliberately minimal and exist solely to trigger a specific parser edge case. The design philosophy is simplicity:

- **Intentional triviality**: `KnownClass` does nothing. It exists only as a symbol for the parser to find.
- **Deliberate bug reproduction**: The JSP is constructed to reproduce the exact attribute ordering that caused the bug, rather than representing a realistic page structure.
- **Regression guard**: Once the parser fix lands, these fixtures ensure the ordering issue does not reappear in future changes.

```mermaid
flowchart LR
    JSP["BugCa002 JSP Test Fixture"] -->|imports| CLASS["KnownClass"]
    JSP -->|triggers| BUG["BUG-CA-002: attribute order bug"]
    BUG -->|tests| PARSER["JSP Parser"]
    PARSER -->|should handle| ORDER["Attribute order independence"]
```

The diagram above shows the interaction model: the JSP page imports `KnownClass` via a page directive with non-standard attribute ordering, which previously triggered the parser bug. The fix ensures the parser handles attributes as an unordered set rather than a positional sequence.

### Attribute Order Independence

A key architectural principle underpinning this fix is that JSP directive attributes are **a set, not a sequence**. The JSP specification does not guarantee attribute ordering within a directive, so parsers should parse each `key=value` pair independently. This module validates that invariant.

## Dependencies and Integration

- **Inbound**: This package is a leaf — nothing within the broader project consumes or references code in `com.example`. It is driven entirely by external test harnesses that invoke the JSP parser against the fixture.
- **Outbound**: `KnownClass` has no dependencies. It imports nothing and extends nothing beyond `java.lang.Object`.
- **External system**: The JSP parser (outside this module) is the primary consumer. The parser reads the JSP page directive, resolves the `import` attribute, and should produce a `jsp_view` node with `referenced_classes` populated — regardless of attribute order.

## Notes for Developers

- **This is a test fixture, not production code.** Do not refactor or extend with business logic. Its sole purpose is to exercise a specific parser edge case.
- **The JSP filename contains a space** (`BugCa002Language Before Import.jsp`). File-handling logic in this directory must be robust to whitespace in filenames.
- **The class is intentionally trivial.** If you need to add test cases, add new classes rather than modifying `KnownClass`.
- **Related test fixtures** exist in the sibling `bug-ca-002-attr-order` project directory for additional variations on attribute ordering within JSP page directives.