# Com / Optage / Model

## Overview

The `com.optage.model` module appears to collect small data-holder types used to represent metadata extracted from source files and test-class classification. It does not contain business workflows or external integrations; instead, it provides the structured objects that other parts of the system can populate, inspect, and render.

The classes in this package are simple, immutable-by-convention DTO-style models with constructors, getters, and `toString()` helpers. Several of them mirror common documentation concepts such as file headers, revision history, business labels, and change markers, which suggests this module exists to normalize source annotations into a consistent in-memory form.

## Key Classes and Interfaces

### `BusinessLabel`

Source: [`src/main/java/model/BusinessLabel.java`](src/main/java/model/BusinessLabel.java)

`BusinessLabel` represents a business-facing label attached to a field. The class stores three pieces of information: the field name, the Japanese label text, and the source from which the label was derived.

This class is intentionally minimal. It exists so that label extraction logic can produce a structured record instead of passing around raw strings. The implementation has only one constructor, three getters, and a `toString()` method for diagnostics.

**Key methods:**
- `BusinessLabel(String fieldName, String label, String source)` - Creates a label record from the field name, human-readable label, and source reference.
- `getFieldName()` - Returns the field name the label belongs to.
- `getLabel()` - Returns the label text.
- `getSource()` - Returns the source description or source snippet reference.
- `toString()` - Formats the object as `BusinessLabel{field=..., label=..., source=...}` for logging.

### `ChangeMarker`

Source: [`src/main/java/model/ChangeMarker.java`](src/main/java/model/ChangeMarker.java)

`ChangeMarker` models a code change annotation. It stores a ticket identifier, version, operation type, author, date, and the line range that the marker covers.

This appears to be used for tracking source edits or transformation boundaries in code comments. The `opType` field is explicitly documented as `ADD`, `MOD`, or `DEL`, which suggests the class is meant to preserve change-intent metadata alongside the source span. The constructor is wrapped in comment markers in the source, reinforcing that this object is part of a change-tracking convention.

**Key methods:**
- `ChangeMarker(String ticketId, String version, String opType, String author, String date, int lineStart, int lineEnd)` - Creates a marker with ticket and line-range metadata.
- `getTicketId()` - Returns the related ticket or work item ID.
- `getVersion()` - Returns the version tag associated with the change.
- `getOpType()` - Returns the operation type string.
- `getAuthor()` - Returns the author name.
- `getDate()` - Returns the date string.
- `getLineStart()` - Returns the first line number covered by the marker.
- `getLineEnd()` - Returns the last line number covered by the marker.
- `toString()` - Formats the marker as a compact diagnostic string.

### `FileHeader`

Source: [`src/main/java/model/FileHeader.java`](src/main/java/model/FileHeader.java)

`FileHeader` captures the metadata that appears at the top of a source file: system name, module name, author, creation date, purpose text, revision count, and revision history.

This class provides the main container for file-level documentation. Its nested `RevisionEntry` class represents one revision-history row, allowing the header to carry both current file metadata and a structured change log. Together, these two types model the kind of header block often found in code generated from documentation conventions.

**Key methods on `FileHeader`:**
- `FileHeader(String systemName, String moduleName, String author, String createdDate, String purposeJa, int revisionCount, List<RevisionEntry> revisionHistory)` - Builds a header from all known file metadata.
- `getSystemName()` - Returns the system name.
- `getModuleName()` - Returns the module name.
- `getAuthor()` - Returns the file author.
- `getCreatedDate()` - Returns the creation date.
- `getPurposeJa()` - Returns the Japanese purpose statement.
- `getRevisionCount()` - Returns the revision count.
- `getRevisionHistory()` - Returns the revision history list.

**Key methods on `RevisionEntry`:**
- `RevisionEntry(String version, String date, String author, String ticket, String descriptionJa)` - Creates one revision record.
- `getVersion()` - Returns the revision version.
- `getDate()` - Returns the revision date.
- `getAuthor()` - Returns the revision author.
- `getTicket()` - Returns the ticket ID tied to the revision.
- `getDescriptionJa()` - Returns the Japanese revision description.

### `OptageCombinedTarget`

Source: [`src/main/java/model/OptageCombinedTarget.java`](src/main/java/model/OptageCombinedTarget.java)

`OptageCombinedTarget` is a sample target class that combines several extraction patterns in one place. The class-level comment says it exists to test extraction patterns A, B, C and `is_test` behavior, which makes it look like a fixture used by tooling or parsers rather than a production domain object.

The fields `customerId`, `subscriptionId`, and `status` are commented with Japanese business labels, while the methods are wrapped in versioned change markers. This makes the class useful as an integration sample for verifying that field-label extraction and change-marker detection both work on the same source file.

**Key methods:**
- `processSubscription()` - Prints `Processing subscription...` to standard output. This appears to represent an added business operation in the sample file.
- `cancelSubscription()` - Prints `Canceling subscription...` to standard output. The surrounding comments mark it as a modification in version `v1.1.0`.

### `TestInfo`

Source: [`src/main/java/model/TestInfo.java`](src/main/java/model/TestInfo.java)

`TestInfo` stores the result of a test-class classification step. It records a class name, a boolean flag indicating whether the class is considered a test, and a list of detection signals that justify the classification.

This class is a lightweight explanation object: it does not perform detection itself, but preserves the output of whatever analysis decided that a class is or is not a test. Keeping the signals alongside the boolean makes the decision easier to audit and debug.

**Key methods:**
- `TestInfo(String className, boolean isTest, List<String> detectionSignals)` - Builds a test-class record.
- `getClassName()` - Returns the class name being classified.
- `isTest()` - Returns whether the class is considered a test.
- `getDetectionSignals()` - Returns the signals used to reach that conclusion.
- `toString()` - Formats the object for logging.

## How It Works

The module works as a set of small record-like classes that other code can assemble into higher-level analysis results.

1. Source parsing or extraction logic identifies an artifact such as a file header, a business label, a change marker, or a test-class signal.
2. The extractor creates one of the model objects in this package to capture that finding in a structured way.
3. Consumer code can then read the object through its getters, serialize it, compare it, or log it via `toString()`.

A typical file-analysis flow for this package would look like:
- Parse a file header into `FileHeader` and its `RevisionEntry` list.
- Detect field comments and map them to `BusinessLabel` objects.
- Detect inline version markers and capture them as `ChangeMarker` objects.
- If the file is a candidate test class, capture the classification outcome in `TestInfo`.
- For sample or fixture input, use `OptageCombinedTarget` to exercise all of those patterns together.

```mermaid
flowchart TD
Module["com.optage.model"] --> BusinessLabel["BusinessLabel"]
Module --> ChangeMarker["ChangeMarker"]
Module --> FileHeader["FileHeader"]
FileHeader --> RevisionEntry["RevisionEntry"]
Module --> OptageCombinedTarget["OptageCombinedTarget"]
Module --> TestInfo["TestInfo"]
BusinessLabel --> LabelData["Business label metadata"]
ChangeMarker --> ChangeData["Change marker metadata"]
FileHeader --> HeaderData["File header metadata"]
OptageCombinedTarget --> SubscriptionOps["Subscription operations"]
TestInfo --> TestData["Test detection metadata"]
```

## Data Model

This module is almost entirely data-oriented.

### File-level metadata
`FileHeader` captures the overall metadata for a source file. Its nested `RevisionEntry` type models a revision history row and is the only nested type in the module.

### Label and change annotations
`BusinessLabel` and `ChangeMarker` both describe annotations found in source code, but they serve different purposes:
- `BusinessLabel` focuses on business terminology attached to fields.
- `ChangeMarker` focuses on versioned change annotations with ticket and line-range context.

### Test classification metadata
`TestInfo` stores classification evidence rather than the detection algorithm itself. This makes it suitable for downstream reporting or debugging.

### Combined sample target
`OptageCombinedTarget` is not a model in the same sense as the others; it is a compact example class that contains both labeled fields and versioned methods so the extraction pipeline can be validated against a realistic mixed case.

## Dependencies and Integration

There are no resolved package dependencies in the indexed evidence for this module, and the source files do not show framework imports beyond `java.util.List` where required.

That said, the types clearly integrate with surrounding parsing or documentation tooling:
- `FileHeader` depends on `List<RevisionEntry>` for revision history.
- `TestInfo` depends on `List<String>` for detection signals.
- `BusinessLabel` and `ChangeMarker` are likely produced by comment or annotation scanners.
- `OptageCombinedTarget` appears to act as input data for those scanners.

## Notes for Developers

- These classes are simple containers, so most behavior is in construction and representation rather than computation.
- `toString()` is implemented on the main model classes, which makes them convenient for logging and debugging.
- The fields are not declared `final`, so the classes are only immutable by convention, not by enforcement.
- `FileHeader.RevisionEntry` is nested inside `FileHeader`, so code that consumes revision history should use the nested type rather than introducing a separate revision model.
- `OptageCombinedTarget` looks intentionally synthetic. Treat it as a sample/fixture class unless you confirm it is used in production logic elsewhere.
- The comments in Japanese are part of the model’s meaning. If you extend the module, preserve the distinction between file metadata, business labels, and change markers so downstream extractors stay predictable.