# Getting Started

## What This Project Does

This project is a Java source code analyzer that inspects classes for field documentation quality and structural consistency. It detects patterns such as ANK-tagged code blocks, inline Japanese labels, missing field descriptions, partial labeling, and file-level documentation headers. The analyzer also identifies test-related edge cases — rogue test-annotated classes in main source, standalone test files, and mixed test framework usage (JUnit vs. TestNG).

## Recommended Reading Order

Start with the wiki pages below in this sequence to build a working mental model of the codebase:

1. **Architecture Overview** — high-level module boundaries and data flow
2. **Module: Field Description Analyzer** — how field-level documentation is extracted and validated
3. **Module: Test Code Detection** — rules for identifying and classifying test classes
4. **Module: Edge Cases** — boundary conditions the analyzer must handle
5. **Module: File Headers** — parsing and validating Javadoc and license headers

After these, refer to the module-specific deep-dives for implementation details.

## Key Entry Points

Because this codebase is organized as a set of independent analysis modules, focus on these entry points in order:

### 1. Main Analyzer Class
Every module under `src/main/java` follows a standard layout:
- Top-level classes (e.g., `OrderProcessor`, `MultiPattern`) — representative inputs the analyzer works with
- No single monolithic entry point — each module runs its own analysis pass

### 2. Module Entry Classes

| Module | Entry Point | Purpose |
|--------|-------------|---------|
| `story1-field-description` | `PatternA`, `PatternB`, `Mixed` | Detects tagged blocks (`ANK-XXXX ADD START/END`) and inline comments as field labels |
| `story2-test-code` | `OrderService`, `TestNGTest`, `RogueTestAnnotated` | Classifies test-related files by location, framework annotation, and package |
| `p2-edge-cases` | `OrderProcessor`, `LargeBusinessLabelClass`, `PartialLabelEntity` | Handles oversized labels, mixed labeled/unlabeled fields, multi-pattern annotations |
| `story4-file-headers` | `WithHeader`, `NoHeader`, `MitLicense` | Parses multi-line Javadoc-style headers, license blocks, and missing-header edge cases |

### 3. Analysis Pipeline

```mermaid
flowchart TD
    A[Java Source Directory] --> B[Discover .java Files]
    B --> C[Parse Class Structure]
    C --> D[Apply Field Description Rules]
    C --> E[Apply Test Code Rules]
    C --> F[Apply File Header Rules]
    D --> G[Report: Labeled Fields]
    D --> H[Report: Unlabeled Fields]
    E --> I[Report: Test Class Location]
    E --> J[Report: Rogue Tests]
    F --> K[Report: Header Status]
    F --> L[Report: License Type]
```

## Project Structure

```
root/
├── story1-field-description/src/main/java/
│   ├── PatternA.java          # ANK-tagged block pattern
│   ├── PatternB.java          # Inline label comment pattern
│   └── Mixed.java             # Mix of labeled and unlabeled fields
├── story2-test-code/src/
│   ├── main/java/com/example/
│   │   ├── OrderService.java             # Production class
│   │   ├── TestNGTest.java               # TestNG-annotated test in main
│   │   ├── RogueTestAnnotated.java       # JUnit test in production source
│   │   └── TestHelper.java               # Shared test utilities
│   ├── test/java/com/example/
│   │   ├── OrderServiceTest.java         # Standard JUnit test
│   │   └── UnannotatedInTest.java        # Non-test class in test package
│   ├── utils/
│   │   └── ImportOnlyTest.java           # Imports Test but has no test methods
│   └── standalone/
│       └── OrderServiceTest.java          # Standalone test file
├── p2-edge-cases/src/main/java/
│   ├── OrderProcessor.java           # Well-documented class with Javadoc
│   ├── MultiPattern.java             # Multiple ANK tags + inline labels
│   ├── PartialLabelEntity.java       # Mixed labeled/unlabeled fields
│   ├── LargeBusinessLabelClass.java  # 40+ fields with Japanese labels
│   ├── EucJpClass.java               # EUC-JP encoded class
│   ├── ProductService.java           # Simple production class
│   └── MixedLabelClass.java          # Mixed label formats
└── story4-file-headers/src/main/java/
    ├── WithHeader.java         # Full multi-line module header
    ├── NoHeader.java           # No Javadoc header (edge case)
    ├── MitLicense.java         # Standard MIT license block
    ├── PartialHeader.java      # Incomplete header (missing sections)
    ├── LongHeader.java         # Very large header file
    ├── Crosslink.java          # Cross-reference header
    ├── NoModuleNoPurpose.java  # Header missing module/purpose
    └── (sub-directory structure)
```

### Directory Naming Conventions

- `story*` — Work items / stories, each with a specific analysis concern
- `p2-edge-cases` — Priority-2 edge cases that require special handling
- `src/main/java` — Source code under analysis
- `src/test/java` — Test classes (only relevant in `story2-test-code`)
- `src/utils` — Shared utility classes referenced by tests

## Configuration

The project uses a modular flat structure with no build configuration files (e.g., `pom.xml`, `build.gradle`, `package.json`) at the root. Each story is an isolated Java module:

| File / Directory | Controls |
|-------------------|----------|
| `story*/src/main/java/` | Source files the analyzer inspects |
| `story2-test-code/src/test/java/` | Test classes vs. production code boundaries |
| `story4-file-headers/` | Header parsing rules (MIT vs. custom formats) |

To add a new analysis module:
1. Create a top-level directory following the `story*` or `p2-*` naming convention
2. Add a `src/main/java/` directory with `.java` files
3. No build system configuration needed — modules are discovered by directory listing

## Common Patterns

### Field Documentation Styles

The analyzer recognizes several field documentation patterns:

**ANK-tagged blocks** — Fields grouped under versioned tags:
```java
// ANK-0001 ADD START
private String syoriDiv = "";  // 処理区分
// ANK-0001 ADD END
```

**Inline comment labels** — Japanese labels in adjacent comments:
```java
private String templateID = "";  // サービスIF_ID
private String identifyCD = "";   // 識別コード
```

**Mixed labeling** — Some fields documented, others not:
```java
private String labeledA = "";  // ラベルA
private String unlabeledB = "";
private String labeledC = "";  // ラベルC
```

### Test Code Patterns

The analyzer distinguishes test classes by location and annotation:

| Pattern | Location | Annotation | Analyzer Treatment |
|---------|----------|------------|--------------------|
| Standard test | `src/test/java/` | `@Test` (JUnit) | Expected test class |
| Rogue test | `src/main/java/` | `@Test` (JUnit) | Flagged — test in production source |
| TestNG test | `src/main/java/` | `@Test` (TestNG) | Flagged — different framework |
| Import-only | `src/utils/` | Imports only | Not a test (no test methods) |
| Standalone | Any | `@Test` | Standalone test file |

### File Header Patterns

File headers follow a structured Javadoc-style format:
```java
/**
 * <プログラム内容>
 *   モジュール名 ： ModuleName
 * <機能概要>
 *   Feature Description
 * <修正履歴>
 *   v72.00.00  2024/01/15  Developer  【ANK-XXXX-00-00】Initial release
 */
```

Edge cases handled:
- **No header** — File starts with package declaration (missing documentation)
- **License-only** — Only a license block, no module metadata
- **Partial header** — Missing one or more required sections
- **MIT license** — Standard open-source license header

### Class Conventions

- All classes are in the default (no-package) or `com.example` package
- Classes have no inheritance hierarchy — they are standalone analysis inputs
- Field names use camelCase; labels are in comments (Japanese or English)
- Method-level documentation (Javadoc) on public methods is preserved in analysis