# Story4fileheaders

## Overview

The `story4fileheaders` module is a test fixture package that provides a collection of Java classes with deliberately varied file header styles. It is designed to be used as input data for tools and tests that validate file header detection, linting, or documentation-generation capabilities — ensuring that a tool can correctly recognize, parse, and handle files with different header configurations.

The module intentionally covers the spectrum of possible file-header states: complete headers, truncated headers, headers with excessive history entries, license-style headers, partial headers missing key fields, and files with no header at all. This makes it a useful reference set when building or testing static-analysis tooling.

## Key Classes and Interfaces

### [Crosslink](story4-file-headers/src/main/java/Crosslink.java:12)

A class with a standard, complete Japanese-style file header. It contains all three expected sections:

- `<プログラム内容>` (program contents) — identifies the module name: `Crosslink`.
- `<機能概要>` (function overview) — provides the purpose: `Crosslink`.
- `<修正履歴>` (revision history) — a single version entry.

Additionally, the class body contains a `private String field` annotated with version-tagged inline comments (e.g. `// v72.00.00 ANK-4427-00-00 ADD START`). This makes `Crosslink.java` a useful test case for tools that need to detect header content *and* version-tagged inline annotations in the same file.

### [LongHeader](story4-file-headers/src/main/java/LongHeader.java:261)

A class whose file header is intentionally massive — it carries **250 version history entries** spanning from v01.00.00 through v250.00.00, each on its own line. The body itself is empty (`public class LongHeader {}`).

This class serves as an edge-case test: can a header-parsing tool handle headers that take up the overwhelming majority of a file's lines? Tools that limit header search depth, or that assume headers are "small," may need to adjust their heuristics to accommodate this scenario.

### [MitLicense](story4-file-headers/src/main/java/MitLicense.java:8)

A class with a standard open-source license header instead of a project-specific one:

```java
/**
 * MIT License
 * Copyright (c) 2024
 */
```

It uses the `/** ... */` Javadoc-style block-comment format, but the content is a license declaration rather than the standard Japanese project header pattern. This is useful for testing whether a tool can distinguish license headers from conventional module headers, or for verifying that a tool does not incorrectly flag a valid MIT license header as a "missing header" violation.

### [NoHeader](story4-file-headers/src/main/java/NoHeader.java:4)

A class with **no header at all** — the `package` statement is the very first line of the file:

```java
package story4fileheaders;

public class NoHeader {}
```

This is the canonical test case for header-missing detection. Any tool scanning this file should flag the absence of a file header. It's also a good baseline for tools that need to generate or insert a default header into files that lack one.

### [NoModuleNoPurpose](story4-file-headers/src/main/java/NoModuleNoPurpose.java:10)

A class with a partial header that includes a revision history section but is missing two critical fields that appear in the standard Japanese header template:

```java
/**
 * <プログラム内容>
 *   システム名      : MinimalSystem
 * <修正履歴>
 *   v1.00.00  2024/01/15  Author  【ANK-0001-00-00】Initial
 */
```

Notably, this header has `<プログラム内容>` but only lists the **system name** (`MinimalSystem`) and is missing both the **module name** and **purpose** fields that appear in the `<機能概要>` section of complete headers. Additionally, it lacks a `<修正履歴>` content — the revision history field is declared but the next comment line `<機能概要>` never appears.

This class tests whether a tool can correctly identify which specific fields are missing and report them with actionable precision.

### [PartialHeader](story4-file-headers/src/main/java/PartialHeader.java:11)

A class with a header that includes the module name and a Japanese-language purpose description, but has **no revision history**:

```java
/**
 * <プログラム内容>
 *   モジュール名    : PartialHeader
 * <機能概要>
 *   照査時およびコース変更時に、契約内容によってサービスオーダ発行を行う
 * <修正履歴>
 */
```

The header identifies:
- **Module name**: `PartialHeader`
- **Purpose**: "照査時およびコース変更時に、契約内容によってサービスオーダ発行を行う" (issues service orders based on contract details during verification and course changes)
- **Revision history**: declared but empty

This tests the boundary between "has a header" and "has a complete header" — a tool might treat this as compliant or flag the empty history section depending on the policy.

### [WithHeader](story4-file-headers/src/main/java/WithHeader.java:12)

A class with a standard, complete Japanese-style file header that includes all three expected sections:

- `<プログラム内容>` — identifies the module name: `WithHeader`.
- `<機能概要>` — provides the purpose: `発行SODCC` (issue SODCC).
- `<修正履歴>` — a single version entry: `v72.00.00  2024/01/15  X.Nguyen  【ANK-4427-00-00】Initial release`.

This is the canonical "correct" file header template. Use it as the reference example when validating that header-parsing tools produce the expected output.

## File Header Format Reference

All classes in this module use (or omit) the standard Japanese project file header format. A complete header follows this structure:

```java
/**
 * <プログラム内容>
 *   モジュール名    : <ModuleName>
 * <機能概要>
 *   <Purpose description in Japanese>
 * <修正履歴>
 *   v<Version>  <Date>  <Author>  【<JiraKey>】<Description>
 */
```

| Section | Tag | Description |
|---|---|---|
| Program contents | `<プログラム内容>` | Contains the module name (`モジュール名`) |
| Function overview | `<機能概要>` | One-line Japanese description of the module's purpose |
| Revision history | `<修正履歴>` | Chronological list of version changes in the format `vX.YY.ZZ  DATE  AUTHOR  【TICKET】Description` |

## Class Relationship Diagram

The seven classes are all siblings within the same package, each representing a distinct header scenario:

```mermaid
flowchart TD
    A["story4-file-headers"] --> B["Crosslink"]
    A --> C["LongHeader"]
    A --> D["MitLicense"]
    A --> E["NoHeader"]
    A --> F["NoModuleNoPurpose"]
    A --> G["PartialHeader"]
    A --> H["WithHeader"]
    B --> B1["Standard Japanese header
with module name + purpose
plus version-tagged inline comments"]
    C --> C1["Very long header
(250+ version entries)"]
    D --> D1["MIT License header"]
    E --> E1["No header at all"]
    F --> F1["Header with system name
missing module name and purpose"]
    G --> G1["Header with module name
and purpose but empty history"]
    H --> H1["Standard Japanese header
with module name + purpose
+ revision history"]
```

## How It Works

This module is not an application in itself — it contains no executable logic, no methods, and no external dependencies. Its purpose is purely structural: each file represents a different file-header pattern that a header-analysis tool might encounter.

A typical workflow using this module as input:

1. A tool scans the `story4-file-headers` package.
2. For each `.java` file, it identifies the file header by scanning from the top of the file for a `/**` block comment or the `package` declaration.
3. It classifies the header into one of these categories:
   - **Complete**: all three sections present (`WithHeader`, `Crosslink`)
   - **Excessive**: header has an unusually large number of version entries (`LongHeader`)
   - **License-style**: standard open-source license text (`MitLicense`)
   - **Missing**: no header at all (`NoHeader`)
   - **Partial - missing fields**: header exists but lacks module name or purpose (`NoModuleNoPurpose`)
   - **Partial - missing history**: header has module name and purpose but empty or absent revision history (`PartialHeader`)
4. It reports the classification, optionally extracting structured data (module name, purpose, version history entries) from headers that contain them.

## Data Model

Each file header, when present, can be parsed into the following logical structure:

| Field | Source tag | Example |
|---|---|---|
| Module name | `<プログラム内容>` → `モジュール名` | `Crosslink`, `PartialHeader` |
| Purpose | `<機能概要>` | `発行SODCC`, purpose in Japanese |
| Revision history entries | `<修正履歴>` → each version line | `v72.00.00  2024/01/15  X.Nguyen  【ANK-4427-00-00】Initial release` |
| License text | N/A (no standard tag) | `MIT License`, `Copyright (c) 2024` |

Each revision entry in `<修正履歴>` follows a consistent pattern:

| Sub-field | Position | Example |
|---|---|---|
| Version | first token | `v72.00.00` |
| Date | second token | `2024/01/15` |
| Author | third token | `X.Nguyen` |
| Ticket key | fourth token, in brackets | `【ANK-4427-00-00】` |
| Description | final token | `Initial release` |

## Dependencies and Integration

This module has no external package dependencies, no imports, and no cross-module relationships. It is a self-contained fixture. Other modules or tools that reference it do so as test data — a header-parsing utility, a documentation generator, or a code quality linter might import this package solely to run against its varied files.

## Notes for Developers

- **No executable code**: None of these classes contain methods, fields (except the single `field` in `Crosslink`), or constructors. They are deliberately empty of logic.
- **All classes are `public`**: Every class uses the `public` modifier so that tools or tests can import them from outside the package if needed.
- **Same package, same purpose**: All 7 classes are in `package story4fileheaders` — there are no sub-packages or nested class hierarchies.
- **Japanese headers**: Most files use Japanese-language comments (`プログラム内容`, `機能概要`, `修正履歴`). This is a standard convention in the originating project. When building tools, consider that the header structure is defined by these section tags rather than by English keywords.
- **Scalability**: If you add new classes, follow the pattern of creating a new file with a single class that has exactly one header style. The naming convention (`Crosslink`, `NoHeader`, `PartialHeader`, etc.) suggests each file represents one distinct header scenario. Keep it simple — no methods, no fields, no imports.
- **The LongHeader file is a stress test**: At 250+ version entries, `LongHeader.java` is the largest file by line count (262 lines). It's useful for verifying that tools handle headers that consume most or all of a file without errors or performance issues.