# Getting Started

## What This Project Does

This codebase is a small Java parsing and documentation-extraction toolkit. It scans source files for Optage-specific conventions such as file headers, business labels in comments, versioned change markers, and test-class signals, then turns those findings into simple model objects.

If you are new here, think of it as a source-analysis pipeline: parsers detect patterns, models hold the extracted data, and tests show the expected behavior end to end.

## Recommended Reading Order

1. Read the repository overview in [` .codewiki/overview.md`](../overview.md) to understand the big picture.
2. Read the package summary in [` .codewiki/com/optage.md`](../com/optage.md) to see how the `model` and `parser` areas fit together.
3. Read the model reference in [` .codewiki/com/optage/model.md`](../com/optage/model.md) to learn the data objects returned by the extractors.
4. Then read the parser tests under [`src/test/java`](../../src/test/java), especially [`IntegrationTest.java`](../../src/test/java/IntegrationTest.java) and [`TestDetectorTest.java`](../../src/test/java/TestDetectorTest.java), to see real examples of how the code is expected to behave.

If you only have time for one path, start with the tests. They reveal the input patterns, the expected outputs, and the priority rules used by the parser.

## Key Entry Points

The indexed codebase does not surface any highly connected classes, so there is no single central entry point. The most important classes to understand first are the parser classes and the model types they produce:

- [`src/main/java/parser/PatternAExtractor.java`](../../src/main/java/parser/PatternAExtractor.java) — extracts versioned change markers.
- [`src/main/java/parser/PatternBExtractor.java`](../../src/main/java/parser/PatternBExtractor.java) — extracts business labels from inline comments.
- [`src/main/java/parser/PatternCExtractor.java`](../../src/main/java/parser/PatternCExtractor.java) — extracts file headers and revision history.
- [`src/main/java/parser/TestDetector.java`](../../src/main/java/parser/TestDetector.java) — classifies source files as tests or non-tests.
- [`src/main/java/model/FileHeader.java`](../../src/main/java/model/FileHeader.java) — the main file-metadata container.
- [`src/main/java/model/BusinessLabel.java`](../../src/main/java/model/BusinessLabel.java) — represents a field label and its source.
- [`src/main/java/model/ChangeMarker.java`](../../src/main/java/model/ChangeMarker.java) — represents a ticket-linked change annotation.
- [`src/main/java/model/TestInfo.java`](../../src/main/java/model/TestInfo.java) — captures test-class classification and the signals behind it.
- [`src/main/java/model/OptageCombinedTarget.java`](../../src/main/java/model/OptageCombinedTarget.java) — a sample target that combines multiple patterns for integration testing.

## Project Structure

The repository is intentionally small:

- `src/main/java/parser/` contains the extraction logic.
- `src/main/java/model/` contains the result objects used by the extractors.
- `src/test/java/` contains focused unit tests plus an integration test that exercises all patterns together.
- `.codewiki/` contains generated documentation for navigating the codebase.
- `pom.xml` defines the Maven build, Java version, and test dependencies.

A useful mental model is:

`source text -> parser -> model object -> tests / documentation`

## Configuration

The key project configuration is [`pom.xml`](../../pom.xml). It controls:

- Java language level: **11**
- Build coordinates: `com.optage:code-parser:1.0.0`
- Test tooling: **JUnit 5**, **AssertJ**, and **Maven Surefire**
- Utility dependency: **commons-lang 2.6** for regex-related support

There are no obvious application runtime config files in the indexed tree. Most of the behavior appears to be driven by source conventions and parsing rules rather than environment settings.

## Common Patterns

A few patterns repeat across the codebase:

- **One class, one responsibility** — each parser focuses on a single extraction concern.
- **Simple data holders** — model types are lightweight objects with constructors, getters, and diagnostic `toString()` methods.
- **Pattern-based parsing** — the tests show that behavior is driven by annotations, comment markers, file paths, and class names.
- **Signal-based classification** — `TestInfo` preserves the detection signals, not just the final boolean result.
- **Integration-friendly fixtures** — `OptageCombinedTarget` combines multiple conventions in one file so the parsers can be tested together.

## Where to Start When Editing

If you need to change behavior, start by finding the matching test:

- test classification changes → [`TestDetectorTest.java`](../../src/test/java/TestDetectorTest.java)
- change-marker parsing changes → the `PatternAExtractor` tests
- business-label parsing changes → the `PatternBExtractor` tests
- file-header parsing changes → the `PatternCExtractor` tests
- end-to-end changes → [`IntegrationTest.java`](../../src/test/java/IntegrationTest.java)

When in doubt, read the tests first, then trace into the parser class, and only after that inspect the model type it returns.