# Com

## Overview

The `com` package sits at the root level of this project's Java package hierarchy and, at present, contains no directly indexed source files or class symbols within its own trees. Instead, the module serves as a **container namespace** whose content is primarily documented through child wiki pages — most notably `example` — which in turn reference classes living in a sibling module (`story2-test-code`).

The `com.example` subpackage (detailed below) is a **demonstration and test-harness set** rather than a production module. It is intentionally composed of minimal stubs, legacy test patterns, and edge-case scenarios designed to exercise test discovery, indexing, and static-analysis tooling. If you encounter classes or tests scattered across this area of the codebase, they likely originate from this demonstration package.

## Sub-module Guide

### `com.example` — Test Patterns and Anti-Patterns Reference

The `com.example` package is the sole documented child module. It demonstrates five distinct scenarios that commonly appear in real Java projects during framework migrations, legacy code evolution, and tooling integration:

1. **JUnit 3 legacy** — `LegacyTest` extends `junit.framework.TestCase`, representing the pre-annotation testing style. It lives in `src/main/java`, making it both a legacy artifact and a misplacement concern.

2. **Production stubs** — `OrderService` (a no-op service) and `TestHelper` (an empty placeholder) show how production scaffolding begins before feature implementation. These are the conceptual subjects of the test classes.

3. **Rogue tests in main source** — `RogueTestAnnotated` (JUnit 4 `@Test`) and `TestNGTest` (TestNG `@Test`) both carry test annotations but are defined in `src/main/java`. This anti-pattern is intentional: it exists to surface how test discovery tools can be confused when tests reside outside the test source tree.

4. **Properly located tests** — `OrderServiceTest` lives in `src/test/java` with a JUnit 4 `@Test` annotation, representing the correct location for test code.

5. **Unannotated test-class siblings** — `UnannotatedInTest` sits in `src/test/java` but has no `@Test` annotation on any method. This exercises the boundary between location-based and annotation-based test identification.

These classes have **no inter-class dependencies** — none instantiate or reference each other directly. The only conceptual relationships are that `OrderServiceTest` is intended to test `OrderService`, and `TestNGTest` mirrors `RogueTestAnnotated` as a TestNG-style counterpart.

## Key Patterns and Architecture

This module does not implement a production architecture or data flow. Instead, it encodes several **testing-related patterns** worth understanding:

- **Multi-framework coexistence.** JUnit 3 (`TestCase`), JUnit 4 (`org.junit.Test`), and TestNG (`org.testng.annotations.Test`) all appear in the same package. This reflects the real-world fragmentation that occurs during framework migration — a project may accumulate tests from multiple generations of testing libraries without a coordinated migration plan.

- **Source-set boundary violations.** Two test classes (`RogueTestAnnotated` and `TestNGTest`) are placed in `src/main/java`. This demonstrates how boundary violations can skew test metrics, cause tests to run in the application classpath, and lead integration tests to be packaged into production artifacts.

- **Stub-driven development.** `OrderService` and `TestHelper` are empty scaffolds that illustrate the "write the class signature first, fill in the logic later" pattern common in feature scaffolding.

```mermaid
flowchart LR
    subgraph MAIN["src/main/java/com/example"]
        LT["LegacyTest
JUnit 3"]
        OS["OrderService
Stub"]
        RTA["RogueTestAnnotated
JUnit @Test"]
        TH["TestHelper
Empty"]
        TNG["TestNGTest
TestNG @Test"]
    end
    subgraph TEST["src/test/java/com/example"]
        OST["OrderServiceTest
JUnit @Test"]
        UIT["UnannotatedInTest
No annotations"]
    end
    OST -.-> OS
    RTA -.-> OS
    TNG -. "parallels" .-> RTA
```

The diagram above shows logical relationships: `OrderService` is the shared production target referenced by both `RogueTestAnnotated` and `OrderServiceTest`. `TestNGTest` parallels `RogueTestAnnotated` as an alternative-framework counterpart.

## Dependencies and Integration

**Internal:** The `com` package has **no child submodules** of its own (the `example` subpackage is documented as a separate wiki page, not as a code-indexed child). There are **no cross-module relationships** or import patterns detected within the `com` module index.

**External:** Classes in `com.example` depend on third-party test frameworks:

| Import | Framework |
|---|---|
| `junit.framework.TestCase` | JUnit 3 |
| `org.junit.Test` | JUnit 4 |
| `org.testng.annotations.Test` | TestNG |

The module itself has no package-level dependencies and no inter-class references. It is a **leaf module** in the package graph.

## Notes for Developers

- **This is a demonstration package, not production code.** The classes are intentionally minimal — most methods are no-ops and most classes are empty. Do not treat them as templates for production features.

- **Rogue tests should be moved or removed.** If `RogueTestAnnotated` and `TestNGTest` are genuine tests, they belong in `src/test/java`. If they are not tests, their framework annotations should be stripped.

- **JUnit 3 is deprecated.** `LegacyTest` uses `extends TestCase`. Any JUnit 3-style tests in this area should be migrated to annotation-based JUnit 4/5 style.

- **Empty classes are scaffolds.** `TestHelper` and `OrderService.run()` are placeholders. If you are implementing features here, expand these with actual logic.

- **Build tool awareness.** If adding real tests, ensure your Maven `surefire` or Gradle `test` configuration correctly discovers JUnit 4 and TestNG annotations, and that `src/test/java` is configured as the test source root.

- **The parent `com` package has no indexed sources.** All substantive content lives in the `com.example` subpackage, which in turn references files from the `story2-test-code` module. When working in this area, consult `.codewiki/com/example.md` for the detailed class-level documentation.