# Repository Overview

Welcome to the Optage repository. This codebase appears to focus on extracting structured documentation and classification metadata from Java source files, especially conventions embedded in comments and file headers. The implementation is compact and Java-based, with no well-known application framework detected from the available imports. If you're new here, think of it as a small parsing-and-modeling toolkit rather than a full application stack.

The main idea is straightforward: parser classes scan source text for recognizable patterns, and model classes hold the results in simple data objects. That makes the repository easy to approach if you are looking for metadata extraction logic, test detection rules, or sample input files that demonstrate those patterns. A new contributor will likely spend most of their time moving between the parser package and the model package.

## Overview

This repository appears to implement a source-analysis pipeline for Optage-flavored Java files. It recognizes several kinds of structured information:

- file headers and revision history
- business labels embedded in inline comments
- versioned change markers with ticket and line-range metadata
- test-class signals based on annotations, file paths, class names, and superclass names

The code is organized around a small set of focused classes. The parser layer does the detection work, while the model layer provides the objects used to carry the extracted results. There is also a sample combined target class that appears to exist specifically so the extractors can be validated against a file containing multiple kinds of signals.

## Technology Stack

The repository appears to use:

- **Java** for the main implementation and tests
- **JUnit-style tests** under `src/test/java`
- **Regular expressions** for most of the extraction and detection logic
- **Plain model classes** for result storage and diagnostic output

No widely used framework such as Spring, Jakarta EE, or Maven/Gradle-specific application code was obvious from the indexed imports alone. The repository therefore looks like a lightweight Java utility project with a strong emphasis on text parsing.

## Architecture

At a high level, the system appears to follow a simple pipeline:

1. Source text is scanned by parser classes.
2. Each parser focuses on one documentation pattern.
3. The parser creates a model object to represent what it found.
4. Downstream code can inspect the model objects, log them, or use them in higher-level documentation workflows.

The main parts of the architecture are shown below.

```mermaid
flowchart LR
Parser["com.optage.parser"] --> PatternA["PatternAExtractor"]
Parser --> PatternB["PatternBExtractor"]
Parser --> PatternC["PatternCExtractor"]
Parser --> TestDetector["TestDetector"]
PatternA --> ChangeMarker["ChangeMarker"]
PatternB --> BusinessLabel["BusinessLabel"]
PatternC --> FileHeader["FileHeader"]
FileHeader --> RevisionEntry["RevisionEntry"]
TestDetector --> TestInfo["TestInfo"]
PatternA --> CombinedTarget["OptageCombinedTarget"]
PatternB --> CombinedTarget
PatternC --> CombinedTarget
TestDetector --> CombinedTarget
```

The architecture is intentionally narrow. Each extractor appears to own one concern, and the shared model module provides the common data shapes used across those concerns. That separation keeps the parsing rules easy to test and makes the extracted results easier to reason about.

## Module Guide

### `com.optage.model`

This module appears to define the data structures used to hold extraction results. The main types are `BusinessLabel`, `ChangeMarker`, `FileHeader`, `RevisionEntry`, `OptageCombinedTarget`, and `TestInfo`. `BusinessLabel` captures field-level business terminology, `ChangeMarker` captures versioned change annotations, `FileHeader` stores file metadata plus revision history, and `TestInfo` records the result of test-class classification along with the signals that justified it. `OptageCombinedTarget` looks like a synthetic sample class used to exercise several extraction patterns in one file.

### `com.optage.parser`

This module appears to implement the actual detection logic. `PatternAExtractor` scans for versioned change-marker blocks and produces `ChangeMarker` objects. `PatternBExtractor` looks for inline Japanese business labels attached to fields and produces `BusinessLabel` objects. `PatternCExtractor` parses file-header metadata and revision entries into a `FileHeader`. `TestDetector` classifies source files as tests based on annotations, path names, class naming, or superclass hints and produces `TestInfo` objects.

## Getting Started

If you are new to the repository, a good reading order is:

1. Start with `src/main/java/model/FileHeader.java` to understand the main metadata container and its nested `RevisionEntry` type.
2. Read `src/main/java/model/BusinessLabel.java`, `src/main/java/model/ChangeMarker.java`, and `src/main/java/model/TestInfo.java` to learn the result objects shared by the extractors.
3. Move to `src/main/java/parser/PatternCExtractor.java` because it shows the basic pattern of scanning text and constructing a model object.
4. Then read `PatternBExtractor.java` and `PatternAExtractor.java` to see the field-label and change-marker extraction styles.
5. Finish with `TestDetector.java` to understand how test classification is layered by signal strength.
6. Review `src/main/java/model/OptageCombinedTarget.java` as a sample input file that appears to combine multiple patterns in one place.
7. Check the tests under `src/test/java`, especially `IntegrationTest.java`, for the best picture of how the pieces are expected to work together.

A practical first goal for a new developer would be to trace one input file through one extractor and then through the corresponding model class. From there, the rest of the repository should feel like variations on the same theme: detect a pattern, capture it in a model, and verify it with tests.