# Root

## Overview

This top-level package is a **test harness and reference codebase** (identified as `story2-test-code`) that lives at the root of the repository. It does not contain production business logic; instead, it provides a controlled set of stubs, placeholder tests, and edge-case examples designed to exercise test discovery tooling, static analysis, and indexing pipelines. The code is intentionally minimal — most classes are empty scaffolds, no-op methods, or deliberately misplaced test classes — making it useful as a reference for how the surrounding build and analysis infrastructure handles various Java file configurations.

## Sub-module Guide

Three sub-packages branch out from this root, each serving a distinct role within the test harness:

### com.example — Demonstration of Test Patterns and Anti-Patterns

The `com.example` package is the most substantial child module. It contains seven classes spread across both `src/main/java` and `src/test/java`, illustrating common patterns and common mistakes encountered in Java test code:

- **Multiple test frameworks coexisting:** JUnit 3 (`LegacyTest` extending `TestCase`), JUnit 4 (`RogueTestAnnotated`, `OrderServiceTest`), and TestNG (`TestNGTest`) are all present, reflecting the fragmentation seen during framework migrations.
- **Misplaced test classes:** `RogueTestAnnotated` and `TestNGTest` are test classes located in `src/main/java` rather than `src/test/java`. This is an anti-pattern that can confuse test discovery, skew coverage metrics, and inadvertently include test code in the production artifact.
- **Properly located tests:** `OrderServiceTest` in `src/test/java` follows conventions but is itself a no-op stub, illustrating the starting point of test development.
- **Production stubs:** `OrderService` is a minimal service stub that serves as the shared subject under test, referenced conceptually by both `OrderServiceTest` and `OrderServiceTestStandalone`. `TestHelper` is an empty placeholder for future shared test utilities.
- **Edge case:** `UnannotatedInTest` lives in `src/test/java` but has no `@Test` annotations, exercising the boundary between location-based and annotation-based test discovery.

### standalone — Isolated Test Scaffold

The `standalone` package contains a single class, `OrderServiceTestStandalone`, which is a self-contained JUnit 4 test scaffold with no external dependencies. It is intended as an isolated entry point for testing an `OrderService` class that conceptually lives elsewhere (specifically, in the `com.example` package). Its empty `test()` method always passes and is meant to be populated with real assertions.

### utils — Import Analysis Fixture

The `utils` package holds `ImportOnlyTest`, a class whose defining characteristic is that it imports `org.junit.Test` but never uses it. This is intentionally designed as a control case for testing import-usage detectors, ensuring that tools correctly identify unused imports without crashing or producing false positives.

### How the Sub-modules Relate

These three sub-packages are siblings under a common test harness:

- **Shared conceptual subject:** `OrderService` (defined in `com.example`) is the production stub that `OrderServiceTest` (also in `com.example`, under `src/test/java`) and `OrderServiceTestStandalone` (in `standalone`) are both intended to test. This illustrates a test-in-the-same-project pattern where the class under test and its tests coexist in the harness.
- **Complementary testing concerns:** `com.example` covers the broadest ground (multiple frameworks, misplaced files, edge cases), `standalone` provides a clean isolated test case, and `utils` zeroes in on a single import-analysis edge case. Together they form a graduated test suite: from broad pattern coverage (`com.example`) to focused isolation (`standalone` and `utils`).
- **No code-level coupling:** Despite these conceptual relationships, there are no cross-module class references or imports between the sub-packages. Each operates independently, communicating only through shared naming conventions and the implicit subject of `OrderService`.

## Key Patterns and Architecture

### Stub-First Development Pattern

Nearly every class in this codebase follows a **stub-first** approach: classes are created with their signatures (methods, inheritance) but left with empty or no-op bodies. This allows the build and tooling pipeline to be exercised early, before feature implementation begins. The stubs are intentionally incomplete — they compile but perform no work — which makes them safe as reference material while flagging areas that need real implementation.

### Intentional Anti-Pattern Inclusion

The `com.example` package deliberately includes anti-patterns (tests in `src/main/java`, legacy JUnit 3 style, unused imports) to serve as edge cases for tooling validation. This is a design choice — the harness is not just testing that good code works, but also that tooling can detect and report common mistakes. When real features are implemented, these anti-patterns should be resolved.

### Multi-Framework Test Fragmentation

The coexistence of JUnit 3, JUnit 4, and TestNG annotations illustrates the fragmentation that often occurs during framework migration. This is likely intentional to verify that test runners and build tools (Maven Surefire, Gradle Test) can handle all three styles simultaneously.

```mermaid
flowchart TD
    Root["Root story2-test-code
(test harness / reference codebase)"] --> Com["com.example
(demonstration test patterns & stubs)"]
    Root --> Standalone["standalone
(isolated test scaffold)"]
    Root --> Utils["utils
(import analysis fixture)"]
    Com --> OS["OrderService
(service stub)"]
    Com --> LT["LegacyTest
(JUnit 3)"]
    Com --> RTA["RogueTestAnnotated
(JUnit 4 in main)"]
    Com --> TNG["TestNGTest
(TestNG in main)"]
    Com --> OST["OrderServiceTest
(JUnit 4 in test)"]
    Com --> TH["TestHelper
(empty)"]
    Com --> UIT["UnannotatedInTest
(no annotations)"]
    Standalone --> OSTS["OrderServiceTestStandalone
(isolated test)"]
    Utils --> IOT["ImportOnlyTest
(unused import fixture)"]
    OSTS -.-> OS
    OST -.-> OS
```

### Data Flow

There is no production data flow in this module. The only "flow" is the **tooling pipeline**: source files are indexed, test discovery runs against them, static analysis tools scan for issues (unused imports, misplaced tests, legacy patterns), and build tools compile and optionally execute tests. The harness is designed to produce predictable results from each of these tools, making it easy to verify that they work as expected.

## Dependencies and Integration

### Internal Dependencies

| Relationship | From | To | Nature |
|---|---|---|---|
| Conceptual target | `com.example.OrderServiceTest` | `com.example.OrderService` | Test targets the service under test |
| Conceptual target | `standalone.OrderServiceTestStandalone` | `com.example.OrderService` | Test targets the service under test |
| Anti-pattern parallel | `com.example.RogueTestAnnotated` | `com.example.TestNGTest` | Both are misplaced tests in `src/main/java` |

### External Dependencies

| Dependency | Used By | Purpose |
|---|---|---|
| `junit.framework.TestCase` (JUnit 3) | `LegacyTest` | Legacy test base class |
| `org.junit.Test` (JUnit 4) | `RogueTestAnnotated`, `OrderServiceTest`, `OrderServiceTestStandalone`, `ImportOnlyTest` | Test method annotation |
| `org.testng.annotations.Test` (TestNG) | `TestNGTest` | Test method annotation |

### Integration with Build Tooling

This module is designed to integrate with standard Java build and test tooling:

- **Maven Surefire / Gradle Test:** Should discover `OrderServiceTest`, `RogueTestAnnotated` (if misconfigured to scan `src/main/java`), `TestNGTest` (if TestNG is on the classpath), and `OrderServiceTestStandalone`. The mixed annotations and placements exercise the discovery edge cases.
- **Static Analysis:** Tools like PMD, Checkstyle, or SpotBugs would flag the misplaced test classes, unused import in `ImportOnlyTest`, and JUnit 3 legacy pattern in `LegacyTest`.
- **Code Indexing:** The mix of `src/main/java` and `src/test/java` locations for both production and test classes exercises the indexer's ability to distinguish source roots correctly.

## Notes for Developers

- **This is not production code.** Every class is a stub, placeholder, or edge-case fixture. Do not treat these classes as templates for production implementation.
- **Anti-patterns are intentional but temporary.** The misplaced tests (`RogueTestAnnotated`, `TestNGTest`) and unused import (`ImportOnlyTest`) exist specifically to test tooling. In a real project, these should be cleaned up.
- **JUnit 3 is legacy.** `LegacyTest` uses the deprecated `extends TestCase` pattern. If the project moves to JUnit 4 or 5, this class should be migrated to annotation-based style.
- **Empty classes need implementation.** `OrderService.run()`, `TestHelper`, `ImportOnlyTest`, and all no-op test methods are scaffolds. When features are built out, these classes need real logic.
- **The harness is self-contained.** There are no cross-module imports between the three sub-packages. New test fixtures added to `standalone` or `utils` should follow the same naming convention (suffix or prefix that describes what is being exercised).