# Repository Overview

Welcome! If you're reading this, you're likely getting started with `story2-test-code` — a Java-based project that serves as a test harness for exploring and validating test-related tooling. It doesn't implement production business logic; instead, it is deliberately minimal, containing stubs, placeholder classes, and intentionally imperfect test arrangements designed to exercise test discovery, indexing, and static analysis pipelines. Think of it as a living reference for the kinds of edge cases (legacy test styles, rogue test classes in main source, unused imports) that real-world Java projects encounter during framework migrations and refactoring.

## Overview

This repository is a small demonstration codebase organized in the standard Maven directory layout. It contains production-style stubs alongside a variety of test classes — some well-located, some deliberately misplaced — across JUnit 3, JUnit 4, and TestNG. The project is structured around a single top-level module named `com.example`, with auxiliary packages under `standalone` and `utils`. Its primary purpose appears to be serving as a playground for tooling engineers who need a controlled set of inputs to validate test discovery, import analysis, and indexing behavior.

## Technology Stack

The project uses:

- **Java** — The source language for all classes.
- **JUnit 3** (`junit.framework.TestCase`) — Used by `LegacyTest`, representing the legacy test style based on class inheritance rather than annotations.
- **JUnit 4** (`org.junit.Test`) — Used by `RogueTestAnnotated`, `OrderServiceTest`, `OrderServiceTestStandalone`, and imported (unused) by `ImportOnlyTest`.
- **TestNG** (`org.testng.annotations.Test`) — Used by `TestNGTest`, representing an alternative test framework.

No well-known application frameworks, build tools (like Maven or Gradle), or external libraries beyond the test frameworks themselves were detected from import analysis.

## Architecture

```mermaid
flowchart TD
    ROOT["story2-test-code Project root"]
    subgraph COM["src/main/java/com/example"]
        OS["OrderService"]
        LT["LegacyTest
JUnit 3"]
        RTA["RogueTestAnnotated
JUnit @Test"]
        TH["TestHelper
Placeholder"]
        TNG["TestNGTest
TestNG @Test"]
    end
    subgraph TEST["src/test/java/com/example"]
        OST["OrderServiceTest
JUnit @Test"]
        UIT["UnannotatedInTest
No annotations"]
    end
    subgraph SL["standalone"]
        OSS["OrderServiceTestStandalone
Standalone test"]
    end
    subgraph UT["utils"]
        IOT["ImportOnlyTest
Import placeholder"]
    end
    ROOT --> COM
    ROOT --> TEST
    ROOT --> SL
    ROOT --> UT
    OST --> OS
    RTA --> OS
    LT --- OS
    TNG --- RTA
    IOT --> JUNIT[org.junit.Test import]
```

The project root (`story2-test-code`) branches into four logical areas:

1. **Main source** (`com.example`) — Contains the sole production stub (`OrderService`) alongside test classes that are misplaced in the main source set. This is the heart of the demonstration.
2. **Test source** (`src/test/java/com/example`) — Contains properly located test classes, including a JUnit test for `OrderService` and a class with no test annotations at all.
3. **Standalone** — A self-contained JUnit test scaffold intended to exercise standalone test discovery.
4. **Utils** — A minimal package with a placeholder class designed to exercise import-analysis tooling.

## Module Guide

### `com.example` — Main Demonstration Package

This is the core of the repository. It organizes classes across both `src/main/java` and `src/test/java` to illustrate common pitfalls and edge cases. On the production side, `OrderService` is a no-op service stub, and `TestHelper` is an entirely empty placeholder. On the test side, there are five classes that together cover JUnit 3 (`LegacyTest`), JUnit 4 with a `@Test` annotation placed in the wrong source tree (`RogueTestAnnotated`), TestNG in the wrong source tree (`TestNGTest`), a properly-located JUnit test (`OrderServiceTest` in `src/test/java`), and a class sitting in the test tree with no test annotations at all (`UnannotatedInTest`). Together, these classes form a compact catalog of patterns that test discovery tooling must handle — or break on. The package is intended to be read first, as it contains the most classes and the clearest explanation of the project's intent.

### `standalone` — Isolated Test Scaffold

This module contains a single class, `OrderServiceTestStandalone`, which is a self-contained JUnit 4 test with an empty `test()` method. It has no dependencies beyond the JUnit framework and no cross-module relationships. It serves as a controlled "clean slate" test entry point — useful for validating that the test runner correctly discovers and executes tests from a minimal, isolated source layout.

### `utils` — Import Analysis Fixture

The `utils` package holds one class, `ImportOnlyTest`, which imports `org.junit.Test` but never uses it. Its body is empty. This class exists purely as a test fixture for import-analysis tooling — it lets engineers verify that static analyzers, linters, and indexers correctly identify unused imports and handle Java files that declare imports without corresponding usage.

## Getting Started

If you are new to this codebase, here is the recommended reading order:

1. **This overview page** — You are here. It provides the high-level context.
2. **The `com.example` module page** — This is the most content-rich module and explains the full range of patterns the project demonstrates. Read the class descriptions to understand the test framework diversity and the anti-patterns being modeled.
3. **The `standalone` module page** — A short, focused read that walks through a minimal standalone test.
4. **The `utils` module page** — The final module, explaining how unused import analysis is exercised.
5. **Source files** — Once you have the module-level context, browse directly into the Java source files under `story2-test-code/src/main/java`, `story2-test-code/src/test/java`, `story2-test-code/standalone/`, and `story2-test-code/src/utils/` to see the code itself. Each class is a single file, typically fewer than 10 lines, making them quick to scan.

Key entry points to explore first:

- `OrderService.java` — The sole production class; everything tests this stub.
- `RogueTestAnnotated.java` — A clear example of a test misplacement anti-pattern.
- `LegacyTest.java` — Shows JUnit 3-style testing for framework migration comparisons.
- `UnannotatedInTest.java` — Demonstrates a class that looks like a test but isn't one from the framework's perspective.