# Com / Example

## Overview

The `com.example` package serves as the top-level container for a specialized test and analysis fixture within the codebase. Rather than containing business logic or production code, this area exists to support static analysis tooling — specifically, to provide well-known, importable classes that linting rules (such as the **bug-ca-002** Sonar rule) can resolve against during code quality checks.

This package represents the infrastructure layer of the project's code quality pipeline. It ensures that static analysis rules have reliable targets to validate import-resolution, attribute ordering, and other structural concerns across JSP and other templated files.

## Sub-module Guide

The `com.example` package currently contains one child sub-module:

### `com.example.bugca002`

This sub-module provides a minimal, stub class (`KnownClass`) that acts as an import resolution target for the **bug-ca-002** rule. The rule checks that JSP `<jsp:useBean>` or `<%@ page import %>` directives appear in a canonical order (e.g., alphabetical or grouped by scope). `KnownClass` gives the rule a concrete class to validate against.

#### How `bugca002` fits into the larger picture

The sub-module plays a structural, non-behavioral role:

1. **Import resolution target.** When the JSP file `BugCa002Language Before Import.jsp` imports `com.example.bugca002.KnownClass`, the static analysis engine traces that import to confirm the rule can successfully resolve the class reference. Without this class, the import would fail to resolve and the rule could not be tested.

2. **Static analysis fixture.** The `bugca002` sub-module is a fixture in a test harness for SonarQube rules. It follows a project-wide convention where packages are named after their corresponding rule ID (e.g., `bugca002` for rule `bug-ca-002`), ensuring each rule has an isolated, predictable import target.

3. **Minimal footprint by design.** The class is intentionally empty — no fields, no dependencies, no side effects. This keeps the fixture lightweight and ensures it cannot accidentally introduce production bugs or coupling into the analysis pipeline.

#### Sub-module interaction diagram

```mermaid
flowchart LR
  JSP["BugCa002Language Before Import.jsp"] -->|imports| KC["KnownClass"]
```

The single interaction here shows the JSP file importing `KnownClass`, which the **bug-ca-002** rule examines for correct attribute ordering. There are no other sub-modules or dependencies in this area.

## Key Patterns and Architecture

### Fixture-Based Testing Pattern

The architecture of `com.example` follows a fixture-based testing pattern. Classes in this package are not intended to be used at runtime; they exist as structural scaffolding for static analysis. This pattern has several implications:

- **Predictability.** Since the classes are minimal and have no dependencies, their behavior is entirely deterministic. Static analysis tools can always resolve them without concern for external state or version incompatibilities.

- **Isolation.** Each rule gets its own package (e.g., `bugca002`), which prevents cross-rule interference. If one rule's fixture changes, it cannot break another rule's test data.

- **Maintainability.** The empty-body design means these classes require virtually no maintenance. Adding business logic would convert a test fixture into production code, introducing unnecessary risk.

### Import-Resolution Validation

The core mechanism this area supports is import resolution validation. When a JSP or JSF file declares an import (e.g., `<%@ page import="com.example.bugca002.KnownClass" %>`), the static analysis engine traces the import reference to confirm:

1. The class exists and is resolvable from the file's context.
2. The import appears in the correct order according to the relevant linting rule.
3. No unresolved or dangling references exist.

`KnownClass` is the anchor point for this chain of validation.

### Design Decisions

- **Empty class body.** The `execute()` method on `KnownClass` is empty but present, ensuring that analyzers which scan for member presence do not skip or flag the class incorrectly.

- **No data model.** This area has no entity classes, DTOs, or persistent structures. It does not participate in any data flow or request lifecycle.

- **No outbound dependencies.** The sub-module does not depend on any other packages, which keeps it isolated and safe from cascading changes.

## Dependencies and Integration

### Inbound Dependencies

| Consumer | What it does |
|---|---|
| `BugCa002Language Before Import.jsp` | Imports and references `KnownClass` from `com.example.bugca002` |

There are no outbound package dependencies from the `com.example` package or its children. The package is a dependency sink — it is consumed by other files but does not consume anything itself.

### Cross-Module Context

```mermaid
flowchart LR
  JSP["BugCa002Language Before Import.jsp"] -->|imports| BUGCA002["com.example.bugca002.KnownClass"]
```

This area is a leaf in the module dependency graph. It does not depend on any other packages, and it does not feed data or behavior into any other subsystem. Its role is purely as a reference target for static analysis.

### No Child Modules

This package has no further sub-packages beyond `bugca002`. All related fixtures should live directly under `com.example` to maintain the one-rule-per-package convention.

## Notes for Developers

- **Do not remove.** Despite its simplicity, this package is required by the `bug-ca-002` analysis fixtures. Deleting `KnownClass` or its package would break the JSP file that references it and likely cause import-resolution failures in the static analysis pipeline.

- **Keep it minimal.** Classes in this area are intentionally stubs. Adding business logic, dependencies, or side effects would turn a test fixture into production code, introducing unnecessary risk and maintenance burden.

- **Package naming convention.** The `bugca002` package name follows the pattern `<rule-id-classifier>` used across the project to group classes that exist solely as test data for specific SonarQube rules. New test fixtures for other rules should follow the same pattern: create a package named after the rule, place a minimal class inside, and reference it from the appropriate fixture JSP/JSF file.

- **No runtime behavior.** This area does not execute at runtime, does not participate in request lifecycles, and does not manage data. Any developer encountering these classes in a runtime stack trace should investigate why test infrastructure code is being loaded outside of analysis.

- **Growing this area.** If additional Sonar rules need fixture classes, create new sub-packages under `com.example` following the existing convention. Each should contain only the minimal classes required for import resolution, with no business logic or external dependencies.